CustomCat API

Version 1.0

Getting Started:

Select your intended use:

1. I am a seller and I want to use CustomCat's product mock-ups to place products on my website AND have CustomCat fulfill my orders. 2. I am a seller and I have my own product mock-ups. I want to use CustomCat to ONLY fulfill my orders. 3. I am a site owner that enables multiple sellers to upload designs and sell products. I have my own mock-ups and I want to use CustomCat to ONLY fulfill my orders. I want to handle all transactions outside of CustomCat. CustomCat will charge me directly and will not provide support for my sellers. 4. I am a site owner that operates a platform for users to sell products. I want my sellers to use CustomCat features and technology to upload designs and generate products to sell on my site. I want CustomCat to handle all seller transactions and I am not involved. CustomCat will provide support for my sellers.

Authentication:

Authentication and identification to the CustomCat API is done by providing an API Key on every request. CustomCat also requires that all communication with the API is secured using TLS. Requests made over HTTP or without a proper API Key will fail.

CustomCat provides two types of API Keys: Read and Write.

You can manage your API Keys from your account.

Treat your API Keys as passwords, keep them secret. API Keys give full read/write access to your account, so they should not be included in public repositories, emails, client side code, etc. If your key gets leaked, you can disable it through your account under API Keys

Resources:

catalog

Description:

Catalog is the full list of products available on CustomCat. Please note: an order line item that contains both a front and back print will add a $5 fee for the back print to the product.

Endpoints:

/catalog GET

get
required string api_key
optional string category (default: Direct To Garment)
Options: Direct To Garment and Sublimation
optional string subcategory (default: "")
optional numeric page (default: 1)
Page to show. Total number of products returned in header value 'X-Total-Count'
optional numeric limit (default: 25)
Number of products to return per page. Max is 250.

/catalog/{catalog_product_id} GET

get
required string api_key
required numeric catalog_product_id

/catalog/sku/{catalog_sku_id} GET

get
required string api_key
required numeric catalog_sku_id

catalogcategory

Description:

List the available product categories and subcategories to narrow the catalog list. 

[
   {
      "category": "Direct to Garment",
      "category_url_slug": "direct-to-garment",
      "subcategories": [
         "Sweatshirts",
         "T-Shirts"
      ]
   },
   {
      "category": "Sublimation",
      "category_url_slug": "sublimation",
      "subcategories": [
         "Bags"
      ]
   }
]

Endpoints:

/catalogcategory GET

get
required string api_key

/catalogcategory/{category_url_slug} GET

get
required string api_key
required string category_url_slug

design

Response: 
[
   {
      "embroidery_url": "https://...",
      "design_id": 4773,
      "tags": "hats,embroidery",
      "default_product_id": 0,
      "digital_url": "https://...",
      "design_name": "CustomCat Logo",
      "last_updated": "August, 31 2017 15:36:20",
      "default_product_name": ""
   },
   {
      "embroidery_url": "",
      "design_id": 4772,
      "tags": "mugs",
      "default_product_id": 1032,
      "digital_url": "https://...",
      "design_name": "CustomCat Logo Mugs",
      "last_updated": "August, 31 2017 15:36:18",
      "default_product_name": "21504 15 oz. White Mug"
   }
]

/design GET

get
required string api_key
optional numeric page (default: 1)
Page to show.
optional numeric limit (default: 25)
Number of designs to return per page. Max is 250.
optional numeric since_id (default: 0)
Restricts to designs created after a specified id
optional string updated_since (default: "")
Restricts to designs created or updated since specified date

order

Description:

The orders API allows you to create, view, update, and delete individual orders to be fulfilled by CustomCat. Only items to be fulfilled by CustomCat should be included in the order. Please note: a line item that contains both a front and back print will include a $5 fee for the back print. 

{
	"shipping_first_name": "Joe",
	"shipping_last_name": "Testing",
	"shipping_address1": "1300 Rosa Parks Blvd ",
	"shipping_address2": "",
	"shipping_city": "Detroit",
	"shipping_state": "MI",
	"shipping_zip": "48216",
	"shipping_country": "US",
	"shipping_email": "no-email@customcat.com",
	"shipping_phone": "555-555-5555",
	"shipping_method": "Economy",
	"items": [
		{
			"catalog_sku": "39515",
			"design_url": "https://myimage-url.com/front_design_order.png",
			"design_url_back": "https://myimage-url.com/back_design_order.png",
			"quantity": 1
		},
		{
			"catalog_sku": "48301",
			"design_url": "https://myimage-url.com/front_design_order.png",
			"quantity": 3
		}
	],
	"sandbox": "1",
	"api_key": "29481-3D34EC-948103-1485F19"
}
	

{
	"shipping_first_name": "Joe",
	"shipping_last_name": "Testing",
	"shipping_address1": "1300 Rosa Parks Blvd ",
	"shipping_address2": "",
	"shipping_city": "Detroit",
	"shipping_state": "MI",
	"shipping_zip": "48216",
	"shipping_country": "US",
	"shipping_email": "no-email@customcat.com",
	"shipping_phone": "555-555-5555",
	"shipping_method": "Economy",
	"items": [
		{
			"sku": "22-115-4774-254",
			"quantity": 1
		},
		{
			"sku": "30-188-4776-335",
			"quantity": 3
		}
	],
	"sandbox": "1",
	"api_key": "29481-3D34EC-948103-1485F19"
}
	

{
	"ORDER_ID": "Your_Order_ID",
	"MSG": "Order added successfully",
	"CUSTOMCAT_ORDER_ID": "184DEF43-CB85-3255-CD3FEF510DE29E0D"
}

Design Placement Presets

When using external designs and passing a "preset_id", the design images will be trimmed and positioned based on the preset passed in.
Preset Info:
  • Digital Products:
    • Preset 1 = Left Front
    • Preset 2 = Full Front
  • Sublimation Products:
    • Preset 4 = Full Front (Mugs,bowls,etc will print on both sides of the product)
    • If using exact size artwork then do NOT pass in a preset.

    • Common Error Messages:

    Code Error Message Description
    400 Bad Request Duplicate Order The order id submitted has already been processed.
    400 Bad Request Invalid state The shipping state/province provided was not found.
    400 Bad Request Invalid Country The shipping country code provided was not found. Please refer to https://en.wikipedia.org/wiki/ISO_3166-1 for proper country codes.
    400 Bad Request There is an issue with the order. {sku} is out-of-stock. A line item in the order contained an out-of-stock sku. The /catalog/sku/{catalog_sku_id} can be used to determine if the sku is in-stock.
    400 Bad Request There is an issue with the order. Please confirm the line item skus. A line item contained an invalid sku.
    400 Bad Request Charge Failed. Our payment processor could not verify the payment method on file as valid. If you feel this is not correct, please try to submit the order again.
    400 Bad Request Invalid Shipping Method. The shipping method was not correct. Refer the /shipping endpoint for valid shipping methods.
    400 Bad Request Customer Email Required. A customer email is required for all orders.
    400 Bad Request Invalid Shipping Address. The city, state, and zipcode did not pass our address verification check. Applicable to U.S. addresses only. More Below.

    Address Verification Services (AVS):

    Both U.S. and International shipping addresses are checked to be complete. Currently only U.S. addresses are verified using an address verification service. We test the city, state and zip code combination against an authoritative database of known addresses. If the address in question matches an address in the official database, the address "validates", meaning it's a real address. Addresses that do not match any addresses in the database are marked as "invalid", meaning the address either doesn't exist or isn't registered with the official postal service. For purposes of the API request we will return a standard 400 error with a description of the error. If available the response will also include a list of possible matches for address correction. Examples of an incomplete and invalid shipping address is shown below.

    Incomplete Shipping Address:

    Charlotte, MI 48843

    Response:

    {
	"error_description":"Incomplete shipping address. Address line 1 is empty."
}

    Bad Address:

    123 Elm Street
    Charlotte, MI 48843

    Response:

    {
	"error_description":"Conflicting ZIP Code\/city\/state information.",
	"suggestions":[
		{
			"city":"Charlotte",
			"country":"US",
			"zipcode":"48813",
			"state":"MI",
			"address1":"123 Elm Street",
			"address2":""
		}
	]
}

    Order Status:

    The following statuses are returned from the order/status/{order_id} endpoint. 

    {

	"CUSTOMER_ADDRESS1": "1300 Rosa Parks Blvd",
	"CUSTOMER_ADDRESS2": "",
	"ORDER_DATE": "March, 27 2018 12:14:45",
	"CUSTOMER_STATE": "MI",
	"CUSTOMER_COUNTRY": "USA",
	"ORDER_TOTAL": 19.47,
	"ORDER_ID": "TestOrder1",
	"CUSTOMER_NAME": "Joe Testing",
	"SHIPMENTS": [
		{
			"TRACKING_ID": "92748901790443643406596477",
			"METHOD": "Expedited Mail Innovations",
			"VENDOR": "UPS",
			"NUMBER_ITEMS": 1
		}
	],
	"LINE_ITEMS": [
		{
			"STATUS": "Shipped",
			"PRODUCT_COLOR_ID": 10258,
			"PRODUCT_NAME": "NL3601 Next Level Men's Premium LS (Royal) S"
		}
	],
	"CUSTOMER_CITY": "Detroit",
	"CUSTOMCAT_ORDER_ID": "C26B18FB-D205-DEF6-EC5168C926375702",
	"ORDER_STATUS": "Shipped",
	"CUSTOMER_ZIP": "48216"
}

    Order Status:

    • Pending - Received and waiting to process
    • Verified - Verified and production started
    • Shipped - Shipped

    Item Status:

    • Processing - Waiting to begin production process
    • Picked / Received - Pulled from stock
    • Printed - Printed
    • Binned - Binned for shipping (waiting on other items from the order to complete)
    • Ready to Ship - All items from order completed and ready to ship
    • Shipped - Shipped
    • Failed QA - The item had a flaw, and will start the production process over.
    • Cancelled - Item Cancelled from the order

    Endpoints:

    /order/{order_id} POST

    post
    required string api_key
    required string order_id
    Your id for the order
    required string shipping_first_name
    required string shipping_last_name
    required string shipping_email
    required string shipping_phone
    required string shipping_address1
    optional string shipping_address2 (default: "")
    required string shipping_city
    required string shipping_state
    required string shipping_zip
    required string shipping_country
    required string shipping_method
    Method from the shipping endpoint
    optional string seller_name (default: "")
    Name of the seller/company to appear on shipping labels. Only needed if you are providing a service to other sellers/companies.
    optional string seller_phone (default: "")
    optional string seller_address1 (default: "")
    optional string seller_address2 (default: "")
    optional string seller_city (default: "")
    optional string seller_state (default: "")
    optional string seller_zip (default: "")
    optional string seller_country (default: "")
    required array items
    JSON array
    - quantity - required - how many of item in the order
    Parameters when using product created through CustomCat
    - sku - required - Product sku from product endpoint

    Parameters when not uploading designs to CustomCat
    - catalog_sku - required - catalog sku from catalog endpoint
    - design_url - required - Fully qualified url to your design
    - design_url_back - optional - Fully qualified url to the back design. Leave 'design_url' blank if design is back only
    - preset_id - optional
    optional string sandbox (default: 0)

    /order/status/{order_id} GET

    get
    required string api_key
    required string order_id
    Your order id
    optional string sandbox (default: 0)

    product

    Description:

    Products is the list of items from the catalog that you want to use on your site.
    Allows you to create, retrieve, update, and delete individual products to be stored by CustomCat.
    A product is design plus either one item or a group of items from the catalog. 

    {
   "products": [
      {
         "product": {
            "product_type": "T-Shirts",
            "variants": [
               {
                  "cost": 6,
                  "price": 19.95,
                  "designs": [
                     {
                        "position": "1",
                        "design_id": 2580581,
                        "image_url": "https://dynamic-imag..."
                     }
                  ],
                  "instock": "true",
                  "title": "Red / Small",
                  "sku": "22-109-2580581-248",
                  "weight": 1,
                  "option1": "Red",
                  "weight_unit": "lb",
                  "option2": "Small"
               },
               {
                  "cost": 8,
                  "price": 21.95,
                  "images": [
                     {
                        "position": "1",
                        "design_id": 2580581,
                        "image_url": "https://dynamic-imag..."
                     }
                  ],
                  "instock": "true",
                  "title": "Red / XX-Large",
                  "sku": "22-109-2580581-367",
                  "weight": 1,
                  "option1": "Red",
                  "weight_unit": "lb",
                  "option2": "XX-Large"
               }
            ],
            "description": "
  • 6.1-ounce, 100% cotton
    • \n\t\t\t\t\t
  • Double-needle neck, sleeves and hem; Roomy Unisex Fit
    • \n\t\t\t\t\t
  • Ash is 99% cotton, 1% poly; Sport Grey is 90% cotton, 10% poly; Dark Heather is 50% cotton, 50% polyester
    • \n\t\t\t\t\t
  • Decoration type: Digital Print
    • \n\t\t\t\t\t
  • Made by Gildan
    • \n\t\t\t\t\tSize Chart",
            "title": "Custom Ultra Cotton T-Shirt",
            "options": [
               {
                  "name": "Color"
               },
               {
                  "name": "Size"
               }
            ],
            "product_id": "22-2580581",
            "tags": ""
         }
      }
   ]
}

    Endpoints:

    /product GET

    get
    required string api_key
    optional numeric page (default: 1)
    Page to show.
    optional numeric limit (default: 25)
    Number of products to return per page. Max is 250.
    optional numeric since_id (default: 0)
    Restricts to products created after a specified id
    optional string updated_since (default: "")
    Restricts to products created or updated since specified date

    /product/{product_id} GET

    get
    required string api_key
    required string product_id

    shipping

    /shipping GET

    get
    Returns shipping methods
    required string api_key
    optional string country (default: United States)
    Ignored if country code is provided. United States[default], https://en.wikipedia.org/wiki/ISO_3166-1
    optional string country_code (default: "")
    https://en.wikipedia.org/wiki/ISO_3166-1

    /shipping/{shipping_id} POST

    post
    Returns the shipping cost for an order.
    required string api_key
    required numeric shipping_id
    optional string state (default: "")
    The shipping state/province.
    optional string country_code (default: US)
    https://en.wikipedia.org/wiki/ISO_3166-1
    required array items
    JSON array of objects that contain catalog_sku and quantity being shipped.

    webhook

    Description:

    Webhooks are a useful tool for shops that want to execute code after a specific event happens on CustomCat. Instead making an API call to check if a specific event has occured, you can register webhooks, which send an HTTP request from CustomCat telling your shop that the event has occurred.

    Topics:

    The topic is a combination of the resource (ex. order) and event (ex. shipped)

    Available Topics:
    Resource Event Topic Description
    Order shipped order-shipped Full order has shipped. 
     {
	"api_key": "{Read-Only API key}",
	"order_id": "{Your_Order_Id}",
	"customcat_order_id": "{CustomCat's_Order_Id}",
	"tracker_number": "{Tracking_Number}#",
	"tracking_url": "{Tracking_URL}"
}
    Order partial-shipment order-partial-shipment If multiple shipments are needed. Order shipped is called when the last item is shipped. 
     {
	"api_key": "{Read-Only API key}",
	"order_id": "{Your_Order_Id}",
	"customcat_order_id": "{CustomCat's_Order_Id}",
	"tracker_number": "{Tracking_Number}#",
	"tracking_url": "{Tracking_URL}",
	"items_remaining:": {number_of_items_remaining}
}
    Product created product-created The seller creates a new product in CustomCat
    Product deleted product-deleted The seller deletes a product in CustomCat
    Product updated product-updated The seller updates a product in CustomCat
    Design rejected design-rejected A design maybe rejected because of quality, copyright infringement, etc 
     {
   "design_url":"{design_url}",
   "reason":"{Reason design was rejected}",
   "orders":[
      {
         "order_id":"{your_order_id}",
         "customcat_order_id":"{CustomCat_Order_id}",
         "items":[
            {
               "catalog_sku":"{catalog_sku}",
               "quantity":"{quantity ordered}"
            }
         ]
      }
   ]
}

    Endpoints:

    /webhook PUT POST GET

    get
    required string api_key
    put
    required string api_key
    required string topic
    required string url
    post
    required string api_key
    required string topic
    required string url

    Error Codes & Responses

    HTTP Status Codes

    The CustomCat API attempts to return appropriate HTTP status codes for every request.

    Code Text Description
    200 OK Success!
    304 Not Modified There was no new data to return.
    400 Bad Request The request was invalid or cannot be otherwise served. Usually caused by bad input data. An accompanying error message in the "X-FAIL-MESSAGE" header field will explain further.
    401 Unauthorized API Key was missing or incorrect.
    403 Forbidden The request is understood, but it has been refused or access is not allowed. An accompanying error message in the "X-FAIL-MESSAGE" header field will explain why. This usually occurs when trying to call a write operation using a read-only API key.
    404 Not Found The URI requested is invalid or the resource requested, such as a cart, does not exists. The message in "X-FAIL-MESSAGE" header field will explain why.
    405 Not Allowed The requested verb is not allowed for this resource. For example, trying to do a POST on the "shippping" resource
    500 Internal Server Error Something is broken. Please contact us.
    502 Bad Gateway The API is down or being upgraded.

    If you see an error response which is not listed in the above table, then fall back to the HTTP status code in order to determine the best way to address the error.