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.
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.
/catalog
GET
List the available product categories and subcategories to narrow the catalog list.
View Response[ { "category": "Direct to Garment", "category_url_slug": "direct-to-garment", "subcategories": [ "Sweatshirts", "T-Shirts" ] }, { "category": "Sublimation", "category_url_slug": "sublimation", "subcategories": [ "Bags" ] } ]
/catalogcategory
GET
[ { "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
The orders API allows you to create, view, update, and delete/cancel 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" }
PRESET OPTIONS:
DTG Products:Sublimation Products:
preset_id = 4Code | 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: {sku} - {out of stock status}. | 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.
Out of stock statuses:
|
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. |
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":"" } ] }
The following statuses are returned from the order/status/{order_id} endpoint.
View Order Status Response{ "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:
Item Status:
/order/{order_id}
DELETE
POST
/order/replacement/{order_id}
DELETE
POST
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": "
/product
GET
/shipping
GET
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.
View JSON
{ "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.
View JSON
{ "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
View JSON
{ "api_key": "{Read-Only API key}", "product_id": "{Product_Id}", "message": "Product Created", "product_url": "https://customcat-beta.mylocker.net/api/v1/product/{Product_Id}" } |
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
View JSON
{ "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}" } ] } ] } |
/webhook
PUT
POST
GET
/webhook/{webhook_id}
DELETE
PUT
GET
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.