Getting Started with the CustomCat API
Connect your store or platform to CustomCat and automate print-on-demand fulfillment.
The CustomCat API allows ecommerce businesses, developers, and software platforms to automate print-on-demand fulfillment by connecting their applications directly to CustomCat.
Through the API, you can retrieve product information, submit orders, monitor fulfillment status, and receive shipment notifications.
API access is available on all CustomCat plans: Lite, Pro, and Enterprise.
This guide covers the basic setup process, available integration models, product and order workflows, and testing. For detailed endpoint specifications, visit the CustomCat API Reference.
Set Up Your CustomCat API Connection
Step 1: Create a CustomCat account
Sign in or create a CustomCat account.
API access is included with Lite, Pro, and Enterprise. Your plan determines your applicable production pricing, but an Enterprise account is not required to use the API.
Step 2: Connect an API Store
After signing in:
- Select Connect Store from the left navigation.
- Find the API connection option and select Create API Order.
- Enter your Store Name and Store URL.
- Select Connect.
Your new API Store is the connection your application will use to retrieve products and submit fulfillment orders.
Step 3: Retrieve your API keys
- Open Settings.
- Navigate to Store tab.
- Select your API store from the dropdown.
- Navigate to the API tab.
- Retrieve your API credentials.
CustomCat provides two permission levels:
- Read-only: Retrieve supported information from the API.
- Read-write: Submit orders and perform supported write operations.
Keep API keys confidential and avoid exposing them in public code or browser-based applications.
For screenshots and additional instructions, see How can I generate an API key?.
Choose Your API Integration Model
CustomCat supports two primary API integration models: Self-Managed and Merchant-Managed.
The primary difference is who owns the CustomCat account and who manages the ongoing fulfillment relationship, including billing, order management, and post-production support.
Self-Managed
One business- or platform-owned CustomCat account
- Your business maintains one CustomCat account with Lite, Pro, or Enterprise pricing.
- Your business generates and manages its API credentials.
- Your application submits orders to CustomCat using your account's API key.
- Your business is responsible for managing and monitoring order transmission, processing, and fulfillment status.
- Your business works directly with CustomCat to resolve production, shipping, and post-production issues.
- Your business manages its own billing, payments, pricing arrangements, and overall business relationship with CustomCat.
Best suited for: Businesses and platforms that want direct control over their CustomCat integration and fulfillment relationship, including pricing, order management, billing, and post-production support.
Merchant-Managed
Multiple merchant-owned CustomCat accounts
- Each merchant creates their own CustomCat account and selects Lite, Pro, or Enterprise pricing.
- Each merchant generates an API key and securely connects their account to your platform.
- Your platform submits orders to CustomCat on behalf of each merchant using that merchant's API credentials.
- Your platform is responsible for managing and monitoring order transmission to CustomCat.
- Each merchant is responsible for monitoring order processing and fulfillment status through their CustomCat account.
- Each merchant works directly with CustomCat to resolve production, shipping, and post-production issues.
- Each merchant manages their own CustomCat billing, payments, pricing arrangements, and business relationship.
Best suited for: Ecommerce platforms, print-on-demand software providers, personalization applications, marketplaces, and other businesses supporting independent sellers that want to offer CustomCat fulfillment while allowing merchants to manage their own fulfillment accounts and relationships.
Important: These models determine account ownership, billing, and fulfillment responsibilities. They do not determine how products and artwork are created or submitted. Both models can use CustomCat-created products or externally hosted artwork, depending on the integration's requirements.
Choose Your Product and Order Workflow
Once you've selected your integration model, the next decision is how your application will create products, manage artwork, and submit orders to CustomCat.
CustomCat supports two primary workflows: External Designs and CustomCat-Created Products.
Both workflows are compatible with Self-Managed and Merchant-Managed integrations.
Workflow A: External Designs (Catalog SKU + Artwork URL)
Your application manages products and artwork. CustomCat handles fulfillment.
This workflow is designed for businesses and platforms that already have their own product creation, customization, or ecommerce functionality.
Your application manages the customer-facing experience, including product listings, mockups, personalization, checkout, and payment collection. CustomCat provides the product catalog and handles printing, packaging, and shipping once an order is submitted.
How it works:
- Retrieve available products and variations through the CustomCat Catalog API.
- Identify the appropriate
catalog_skufor each product variation. - Create or retrieve the customer's production-ready artwork through your application.
- Host the artwork at an accessible, direct-download image URL.
- Submit the order to CustomCat using the
catalog_sku,design_url, and required order details. - Retrieve order statuses and tracking information through the API or supported webhooks.
Your application is responsible for:
- Product listings, customer-facing mockups, and customization tools.
- Customer checkout, payments, and any applicable merchant or creator payouts.
- Generating and hosting production-ready artwork.
- Submitting accurate order information to CustomCat.
- Managing the customer-facing order experience.
CustomCat is responsible for:
- Providing supported product catalog information and SKUs.
- Receiving fulfillment orders through the API.
- Manufacturing, packaging, and shipping accepted orders.
- Providing available fulfillment status and shipment tracking information.
Best suited for: Ecommerce businesses, established brands, merchandise platforms, marketplaces, and personalization software providers that already manage their own products and artwork and want CustomCat to serve as their fulfillment provider.
Workflow B: CustomCat-Created Products (Product SKU)
Products are created in CustomCat. Your application retrieves their SKUs and submits orders.
This workflow is designed for merchants and developers who prefer to use CustomCat's existing design upload and product creation tools instead of managing product configurations and production artwork entirely within their own software.
How it works:
- Merchant logs in to CustomCat and selects designated API Store.
- Merchant uploads artwork and creates products through the CustomCat application.
- Your application retrieves completed products and their SKUs using
GET /product. - Store or reference those product SKUs within your application.
- Submit orders to CustomCat using the retrieved product SKUs and required customer order details.
- Retrieve order statuses and tracking information through the API or supported webhooks.
Your application is responsible for:
- Retrieving and referencing the correct CustomCat product SKUs.
- Managing customer-facing product listings, checkout, and payments.
- Submitting accurate order information to CustomCat.
- Managing the customer-facing order experience.
CustomCat provides:
- Artwork upload and design management tools.
- An interface for creating products within your API Store.
- The Products API for retrieving completed products and their SKUs.
- Manufacturing, packaging, shipping, and fulfillment tracking.
Important: Can I view or edit completed API Store products in the CustomCat dashboard?
Not currently. Although products are created through the CustomCat application, completed API Store products and their SKUs do not appear in the dashboard afterward.
These products are retrievable through GET /product, but they cannot currently be viewed or edited through the dashboard's My Products section.
CustomCat is considering adding dashboard management for completed API Store products. If this functionality would improve your workflow, please share your feedback with our team.
Best suited for: Merchants and developers who prefer to configure products and artwork using CustomCat's existing tools rather than building their own product creation workflow.
How Do the Integration Model and Order Workflow Work Together?
Your integration model determines who owns the CustomCat account, who pays for fulfillment, and who manages the ongoing fulfillment relationship with CustomCat.
Your order workflow determines how products and artwork are created, managed, and referenced when submitting orders.
These are two independent decisions. Both Self-Managed and Merchant-Managed integrations can use either External Designs or CustomCat-Created Products.
Example 1: Self-Managed + External Designs
A merchandise platform already has its own storefronts, product builder, mockups, checkout, payment processing, and artwork generation system.
The platform uses its own CustomCat account and API credentials to submit orders with the appropriate catalog_sku, design_url, and other required order details.
The platform manages its customer-facing ecommerce experience and works directly with CustomCat to manage fulfillment, billing, order statuses, and post-production issues.
The platform pays CustomCat directly for fulfillment and CustomCat manufactures and ships the orders and provides fulfillment status and tracking information.
Example 2: Merchant-Managed + External Designs
A personalization software provider allows individual merchants to connect their own CustomCat accounts.
The software manages product personalization, generates artwork, and submits orders to CustomCat using each merchant's API credentials, together with the appropriate catalog_sku, design_url, and required order details.
The software provider manages order transmission, while each merchant maintains their own CustomCat billing, fulfillment monitoring, and post-production relationship.
What if I want to use CustomCat-Created Products instead?
Either integration model can use products created through the CustomCat application.
In that case, the integration retrieves the completed product's sku using GET /product and submits orders referencing that SKU rather than submitting external artwork URLs.
Test Your API Integration
CustomCat supports sandbox validation to help developers test order submission requests before submitting live fulfillment orders.
There are two ways to test your integration:
- Sandbox validation: Verify that your API order request passes validation without creating an order or incurring fulfillment charges.
- Live test order: Submit an actual production order to verify artwork processing, manufacturing, shipping, and order tracking.
How Do I Enable Sandbox Mode?
Include the optional sandbox string field in your order submission request and assign it the value "1".
{ "sandbox": "1" }
This example shows only the sandbox parameter, not a complete order submission payload.
When sandbox mode is enabled, CustomCat validates the request and returns a success or failure response.
Sandbox submissions do not:
- Create production orders.
- Appear in the CustomCat Orders Dashboard.
- Trigger manufacturing.
- Generate fulfillment charges.
Important: A successful sandbox response confirms that the request passed API validation. It does not verify that your artwork was downloaded, rendered, or processed for production.
How Do I Test the Complete Fulfillment Process?
To test the complete order lifecycle, submit a live order without the sandbox parameter.
A live test order allows you to verify:
- Order creation: The order is accepted into CustomCat's production workflow.
- Artwork processing: CustomCat receives and processes the submitted artwork.
- Order status: Your application can retrieve fulfillment updates using
order/status/{your_order_id}. - Shipping and tracking: Shipment and tracking information becomes available once the order ships.
Important: Live test orders are actual production orders and are subject to normal production and shipping charges.
We recommend completing sandbox validation first, followed by a live sample order before launching your integration.
Track Orders and Shipments
Once an order is submitted to CustomCat, your application can retrieve fulfillment information through the API or receive automatic shipment notifications using webhooks.
CustomCat provides two primary ways to monitor fulfillment:
- Order/Item Status API: Retrieve the latest available fulfillment information for a specific order.
- Shipment Webhooks: Automatically receive notifications when an order ships.
How Do I Retrieve Order Status?
Use the Order/Item Status endpoint:
order/status/{your_order_id}
Replace {your_order_id} with the order ID you provided when submitting the order to CustomCat.
Your application can use this endpoint to retrieve available order and item status information, along with applicable shipment and tracking details.
This is useful when your application needs to check an order's current fulfillment status or reconcile information with CustomCat.
How Do I Receive Automatic Shipment Notifications?
CustomCat supports webhooks that notify your application when an order ships.
To create a webhook subscription, send a POST request to:
/webhook
Include the following parameters:
- API key: The API credentials associated with the CustomCat account.
topic:order-shippedurl: The destination URL where CustomCat should send the webhook notification.
Once configured, CustomCat sends shipment notifications to your designated URL when applicable orders ship.
Your application can use the information received to update order records, display tracking information, or notify customers.
Should I Use Webhooks or the Order Status API?
We recommend using shipment webhooks for automatic shipping updates, while retaining the Order/Item Status API for retrieving current order information when needed.
Webhooks reduce the need for repeated status requests, while the Order/Item Status API provides a way to check an order directly.
Important for Merchant-Managed integrations: Your platform can retrieve fulfillment information and receive shipment notifications using each merchant's API credentials. However, the merchant remains responsible for managing their CustomCat account, billing, and production or post-production issues directly with CustomCat.
For complete request and response specifications, refer to the CustomCat API Reference.
Additional Resources and Support
For more information about products, artwork, and integration requirements, explore these resources:
- CustomCat API Reference — Endpoint documentation, parameters, and technical specifications.
- How can I generate an API key? — API Store setup and credential instructions.
- CustomCat Design Placement Presets — Artwork positioning options.
- CustomCat Print Specifications — Artwork dimensions and production requirements.
- CustomCat Product Catalog — Available print-on-demand products.
Need help?
If you're developing a custom integration, building an ecommerce platform, or evaluating a fulfillment partnership, contact CustomCat Support.
Please include a brief description of your intended integration, account ownership model, and technical questions so we can provide the most relevant guidance.