Building a CustomCat API Integration: Developer Workflow Guide

The CustomCat API allows developers to connect ecommerce storefronts, marketplaces, personalization applications, and custom software directly to CustomCat's print-on-demand fulfillment services.

This guide walks through retrieving products, preparing artwork, submitting fulfillment orders, testing requests, handling errors, and tracking shipments.

Who this guide is for: Developers who have already created a CustomCat API Store and are ready to build or improve their integration.

Before you begin: Review Getting Started with the CustomCat API to understand Self-Managed and Merchant-Managed integrations, available order workflows, and account setup.

For complete endpoint specifications, refer to the CustomCat API Reference.

Understand Your Integration Responsibilities

Before writing code, determine which functions your application manages and which functions CustomCat provides.

For a typical Self-Managed integration using External Designs:

Your application handles:

Customer-facing storefronts, product listings, and mockups.
Product personalization and customization tools.
Customer checkout, merchant payments, and applicable creator payouts.
Generating and hosting production artwork.
Selecting the correct CustomCat product variation.
Submitting orders and monitoring their transmission.
Customer-facing order updates and support.

CustomCat handles:

Providing supported product catalog information.
Receiving and processing accepted fulfillment orders.
Manufacturing and printing products.
Packaging and shipping orders.
Providing available order status and tracking information.
Supporting the CustomCat account holder with fulfillment-related issues.

Merchant-Managed integrations: The software platform manages order transmission using each merchant's credentials, while individual merchants manage their CustomCat accounts, billing, fulfillment monitoring, and production or post-production issues.

The technical order workflow may be similar under both models. The primary difference is who owns the CustomCat account and manages the fulfillment relationship.

Step 1: Connect and Authenticate Your Application

Every integration requires an active CustomCat account, a designated API Store, and appropriate API credentials.

Which API Key Should I Use?

CustomCat provides read-only and read-write API credentials.

Read-only: For supported requests that retrieve information.
Read-write: For submitting fulfillment orders and other supported write operations.

For Self-Managed integrations, use credentials associated with your business's API Store.

For Merchant-Managed integrations, connect each merchant using their own CustomCat API credentials.

Security recommendations:

Store credentials securely on your server.
Do not expose API keys in browser-side code or public repositories.
Associate every merchant with the correct account credentials.
Avoid including full API keys in logs or error messages.
Verify the intended merchant account before submitting orders.

See How can I generate an API key? for setup instructions.

Step 2: Retrieve Products and Select the Correct SKU

CustomCat supports two primary order workflows. The most common approach for platforms with existing product creation tools is External Designs.

External Designs: Retrieve a `catalog_sku`

Use the Catalog API to retrieve available products and variations.

Relevant endpoints include:

/catalog
/catalogCategories
/catalog_sku

Your application must identify the correct catalog_sku for the product variation selected by the customer.

For example, a black T-shirt in size Large uses a different catalog SKU from the same shirt in size Medium.

Important: Do not assume one catalog SKU represents every color and size of a product.

CustomCat-Created Products: Retrieve a `sku`

For products created through the CustomCat application within your designated API Store, use:

GET /product

The Products API retrieves completed product information and associated product SKUs.

Important: The Products API does not create products.

Products are created through the CustomCat dashboard, but completed API Store products and their SKUs are not displayed or editable there afterward. They must be retrieved through the Products API.

Should I Use `sku` or `catalog_sku`?

catalog_sku: For orders using External Designs.
sku: For orders referencing products previously created in the CustomCat application.

These identifiers are not interchangeable.

How Do I Check Inventory and Pricing?

The Catalog API provides product and variation information, including available inventory data.

Your application should account for inventory changes and handle products that become unavailable.

CustomCat pricing is account-specific and may vary between Lite, Pro, and Enterprise accounts. Merchant-Managed platforms should not assume every connected merchant has identical product pricing.

See Where can I download a list of CustomCat's Catalog?.

Step 3: Prepare and Host Production Artwork

For External Designs, your application is responsible for creating or obtaining the production artwork and making it accessible to CustomCat.

Production artwork is separate from the product mockups displayed to customers.

Which Artwork Fields Should I Use?

For supported products:

design_url: URL for front artwork.
design_url_back: URL for back artwork.
preset_id: Optional placement preset for front artwork.
preset_back_id: Optional placement preset for back artwork.

Front and back artwork can use different placement presets.

For example, an order with both front and back printing can specify a front placement using preset_id and a separate back placement using preset_back_id.

For a back-only design, use design_url_back without providing a front artwork URL.

Not every product supports every decoration location. Verify product capabilities before exposing decoration choices in your application.

Refer to:

Current limitation: Sleeve printing is not supported through the CustomCat API.

What Makes an Artwork URL Valid?

CustomCat must be able to retrieve the actual image file from the submitted URL.

Your artwork URL should:

Point directly to a supported PNG or JPG image.
Be accessible without authentication.
Allow the image to be downloaded.
Remain available while the order is being processed.
Reference production artwork rather than a mockup webpage.

Amazon S3 and Google Cloud Storage can be used when configured for accessible image delivery.

Google Drive sharing links are not supported for production artwork.

Dropbox links may require ?dl=1 to enable direct downloads.

How Do I Ensure Correct Artwork Size and Placement?

Prepare artwork according to the selected product's print specifications and decoration method.

Refer to:

Use preset_id and preset_back_id where appropriate for supported front and back placements.

Recommendation: Validate artwork dimensions, format, accessibility, and positioning before submitting fulfillment orders.

Step 4: Submit Your Fulfillment Order

Once your application has the correct SKU, production artwork, and recipient information, it can submit an order through the CustomCat Orders API.

How Do I Submit an Order?

Include your order ID in the request URL.

For example:

https://customcat-beta.mylocker.net/api/v1/order/101-102938

In this example, 101-102938 represents the order ID assigned by your application.

Your order request contains shipping information, one or more items, applicable artwork information, and your API credentials.

Example: Complete External Designs Order Request

The following example comes from the CustomCat API documentation. It contains two order items, including a product with front and back artwork.

{   "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": "your key" }

Replace the example artwork URLs, product SKUs, and API key with valid values for your integration.

This request contains "sandbox": "1", so it performs sandbox validation rather than creating a production order.

Example: Successful API Response

A successful request can return:

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

The response includes:

ORDER_ID: Your submitted order identifier.
MSG: The API response message.
CUSTOMCAT_ORDER_ID: The identifier returned by CustomCat.

Important: When sandbox mode is enabled, a successful response does not indicate that a persistent production order was created.

What Information Is Required for Live Orders?

Your application must provide the information required by the Orders API, including the appropriate product identifiers, order items, shipping details, and credentials.

The shipping_phone field is required for live orders, including domestic and international shipments.

Consult the API reference for the complete request schema and shipping method requirements.

Step 5: Test Your Integration Before Launch

CustomCat supports sandbox validation but does not provide a separate sandbox environment with persistent test orders.

We recommend completing sandbox validation first, followed by a live sample order.

How Do I Enable Sandbox Mode?

Include the optional string field:

{   "sandbox": "1" }

When sandbox mode is enabled, CustomCat validates the order submission request and returns a success or failure response.

Sandbox requests do not:

Create persistent production orders.
Appear in the CustomCat Orders Dashboard.
Trigger printing or manufacturing.
Generate fulfillment charges.

Important: Successful sandbox validation does not confirm that artwork was downloaded, rendered, printed, or shipped.

How Do I Test the Complete Fulfillment Process?

Submit a live sample order without the sandbox field.

A live test verifies the actual fulfillment lifecycle, including order creation, artwork processing, production, shipping, and tracking.

Live test orders are subject to normal production and shipping charges.

For integrations generating customized artwork, we recommend inspecting a physical sample before launching.

Step 6: Retrieve Order Status and Receive Shipment Notifications

After submitting an order, your application can retrieve fulfillment information through the Order/Item Status endpoint or receive automatic shipment notifications.

How Do I Retrieve Order Status?

Use:

order/status/{your_order_id}

Replace {your_order_id} with the order ID supplied when submitting the order.

This endpoint returns available order and item fulfillment information, including applicable shipment and tracking details.

How Do I Receive Automatic Shipment Notifications?

POST /webhook

Include:

API key: Credentials for the relevant CustomCat account.
topic: order-shipped
url: The destination where CustomCat should send notifications.

CustomCat sends notifications to your registered URL when applicable orders ship.

Your application can use the tracking information to update internal records or notify customers.

Should I Use Webhooks or the Order Status API?

We recommend webhooks for automatic shipment notifications.

Use the Order/Item Status API when your application needs to retrieve an order's current fulfillment information or reconcile its records.

The confirmed webhook topic is order-shipped. Do not assume that every production-stage status generates a webhook.

Step 7: Handle Errors, Duplicate Orders, and Retries

Reliable integrations must distinguish between orders that were successfully submitted and orders that CustomCat rejected.

This distinction determines whether an order can be resubmitted using the same order ID.

How Do I Identify API Errors?

CustomCat uses HTTP response codes to communicate request outcomes.

Status	Meaning
`200`	Request successful
`304`	No modified data returned
`400`	Invalid request or validation error
`401`	Missing or invalid API credentials
`403`	Request refused or insufficient permissions
`404`	Endpoint or resource not found
`405`	Unsupported HTTP method
`500`	Internal server error
`502`	Gateway unavailable or undergoing maintenance

For applicable errors, inspect the response header:

X-FAIL-MESSAGE

This header provides additional details about why a request was rejected.

Can I Submit the Same Order ID More Than Once?

It depends on whether the order was successfully accepted.

If an order has received a successful API response, CustomCat will reject another submission using the same order ID as a duplicate.

If an order was rejected due to an error, you can correct the issue and resubmit it using the same order ID.

Important: You do not need to generate a new order ID each time you retry a previously rejected order.

When Should I Retry an Order?

Resubmitting a rejected order is appropriate when the condition that caused the failure has been resolved.

For example:

Out-of-stock product

An order is rejected because the selected product is out of stock.

When the product becomes available again or you have removed the unavailable product, your application can resubmit the order using the original order ID.

Banned or unapproved artwork

An order is rejected because its artwork was flagged as a banned/unapproved design.

If CustomCat subsequently approves the design, the order can be resubmitted using the same order ID.

Address validation failure

An order is rejected because the shipping address fails validation.

After correcting the address, resubmit the order using the same order ID.

These examples illustrate an important principle: A rejected order can be corrected and retried without changing its original order ID.

What If My Request Times Out or I Don't Receive a Response?

A missing response is different from an explicit order rejection.

Before retrying, determine whether the original submission may have been accepted.

Recommended handling:

Retain the original order ID and submission details.
Record the response, error message, or timeout.
If the request was explicitly rejected, correct the issue and resubmit using the same order ID.
If the outcome is uncertain, check the order's status or reconcile its submission before retrying.
Retain the same order ID rather than generating a different ID for the same customer order.

If the original order was successfully accepted, a repeated submission using that ID will be rejected as a duplicate.

If the original order failed, a corrected submission using that ID can be accepted.

This allows applications to retry previously rejected orders while maintaining consistent order identifiers.

How Should I Handle Webhook Notifications?

Your application's webhook endpoint should process shipment notifications reliably.

As an integration best practice, associate each notification with the corresponding order and avoid interpreting repeated notifications as additional orders or shipments.

Step 8: Review Your Integration Before Going Live

Before routing customer orders to CustomCat, review the following checklist.

Account and authentication

Correct API Store connected.
API credentials stored securely.
Merchant-managed orders associated with the correct merchant credentials.

Catalog and products

Correct catalog_sku or sku used.
Product variations mapped correctly.
Unavailable products handled appropriately.

Artwork

Artwork URLs permit direct downloads.
Artwork meets product specifications.
design_url and design_url_back are assigned correctly.
preset_id and preset_back_id are configured where appropriate.

Order submission

Order ID included in the request URL.
Required recipient and shipping details provided.
Sandbox validation completed.
Live sample order tested.
API responses and order identifiers recorded.
Rejected orders can be corrected and retried using their original order IDs.

Fulfillment

Order status retrieval working.
Shipment webhooks configured where needed.
Customer-facing tracking updates tested.
Billing and post-production support responsibilities understood.

Frequently Asked Developer Questions

Does CustomCat Build the Storefront or Product Customization Interface?

No. Your application manages the customer-facing ecommerce experience.

CustomCat provides manufacturing and fulfillment capabilities through its API.

Do I Need to Create Products in CustomCat Before Submitting Orders?

Not when using External Designs.

You can submit supported catalog_sku values with externally hosted artwork URLs.

Can Merchant-Managed Platforms Submit Orders for Multiple Merchants?

Yes. Your platform can submit orders using each connected merchant's API credentials.

Each merchant maintains their own CustomCat account and fulfillment relationship.

Can I Retrieve Products Created in CustomCat?

Yes. Use GET /product to retrieve products created within your designated API Store.

Completed API Store products are not currently displayed or editable through the CustomCat dashboard.

Can I Set Different Placement Presets for Front and Back Artwork?

Yes. Use preset_id for the front placement and preset_back_id for the back placement, where supported.

Can I Test an Order Without Creating a Production Order?

Yes. Include "sandbox": "1" for sandbox validation.

Can I Retry an Order Using the Same Order ID?

Yes, if the previous submission was rejected. Correct the problem and resubmit using the original order ID.

If the order was already successfully accepted, a new submission with the same ID will be rejected as a duplicate.

Does CustomCat Support Automatic Shipment Notifications?

Yes. Register an order-shipped webhook through POST /webhook.

Does CustomCat Publish API Rate Limits?

CustomCat does not currently publish general API rate limits. Accounts using the API beyond reasonable levels may be subject to rate limiting.

Design integrations to avoid unnecessary requests.

Additional Developer Resources

Getting Started with the CustomCat API — Account setup, integration models, and order workflows.
Official CustomCat API Reference — Endpoint specifications and response formats.
How can I generate an API key? — API credentials.
CustomCat Design Placement Presets — Artwork positioning.
CustomCat Print Specifications — Production artwork requirements.
Where can I download a list of CustomCat's Catalog? — Catalog and availability information.
Using Prepaid Shipping Labels with CustomCat — Prepaid-label fulfillment options.

Need Technical Assistance?

If you encounter integration problems, contact CustomCat Support.

Include your API Store information, relevant order ID, endpoint, HTTP response status, and any applicable error details.

Never include your full API credentials in support requests.

For exact implementation requirements, refer to the CustomCat API Reference.