Status Information

This guide explains the different status types in the Shirtigo Cockpit system, including order statuses and individual product item statuses.

Table of Contents

• Status Information
  • Order Status Keys
  • Order Product Item Status Keys
• Webhooks
  • How to Choose a URL
  • Available Events
  • Registration
  • Delivery & Verification

Order Status Keys

The following table shows all possible order status values:

Status Key	Description
pending	Order created and payment pending
open	Payment successful
successful	Production preparation
production	In production
shipped	Shipped
clarification	Clarification needed
out-of-stock	Supply shortage
documents-required	Commercial invoice required
processing-failed	Order was cancelled due to failed async image processing
payment-failed	Payment failed
refund	Order cancelled

Handling Failed Status Cases

When an order enters a failed status, specific actions are required to resolve the issue:

Clarification Status

If the order status is clarification, use the Update delivery address endpoint to submit an updated delivery address.

Note: The validation of the new address is performed asynchronously.

Documents Required Status

If the order status is documents-required, use the Upload Merchant Invoice endpoint to submit a customs invoice.

Processing Failed Status

If the order status is processing-failed, check the error in the related design objects and submit the order again with corrected files.

Payment Failed Status

If the order status is payment-failed, this typically occurs due to insufficient credit card funds. You can use the Retry payment endpoint to attempt the payment again.

Important: API orders can only be placed with the following payment methods:

• Prepayment
• Direct debit (requires key account activation)
• Wallet

Order Product Item Status Keys

The following table shows all possible status values for individual order product items that can be received through webhooks:

Status Key	Status Group	Description
pending	preparing	Item was pushed to production system
ordered	preparing	Pick order for item was created
printed	processing	Pick label for item printed and item picked
pretreatment	processing	Product is being pretreated
embroidery	processing	Product is in embroidery process
dtg	processing	Product is being printed
additional	processing	Additional processing step is performed
branding	processing	Product is being branded
passed	processing	Product passed quality control
refused	failed	Product failed quality control and will be reproduced with new item
sorting	successful	Product is in outbound sorting
ready	successful	Product ready for shipping
shipped	successful	Product has been shipped
cancelled	failed	Product has been cancelled

Note: The status progression typically follows the order: preparing → processing → successful/failed. Each product item in an order can have its own status, allowing for detailed tracking of individual items. If a item fails a new one will be created for the same orderProduct.

---

Webhooks

Webhooks provide a way to receive real-time updates for specific events in your Shirtigo Cockpit. This section explains how to register webhooks, available events, and how to verify webhook authenticity.

How to Choose a URL for Your Webhook

To use a webhook, you need to define a publicly accessible URL in your system where webhook requests will be sent. The URL should be able to:

• Accept POST requests.
• Process the incoming JSON payload correctly.
• Respond with a 2xx HTTP status code to confirm successful receipt.

Note: If authentication is required, ensure that the webhook URL can still receive requests without restrictions, as this may interfere with delivery.

Available Webhook Events

Webhooks are triggered by specific events, which are defined by:

• Key: A unique identifier that combines the resource and action.
• Resource: The entity being affected (e.g., Order, Product, Design).
• Action: The type of event occurring (e.g., Created, Updated, Deleted).

Supported Webhook Events

Key	Resource	Action	Description
order.created	Order	created	Triggered when a new order is placed.
order.created-failed	Order	creation-failed	Triggered when an order cannot be created due to an issue (e.g., print file errors).
order.updated	Order	updated	Triggered when an order status changes.
order.shipped	Order	shipped	Triggered when an order is shipped.
order.clarification	Order	clarification	Triggered when additional action is required.
order.canceled	Order	canceled	Triggered when an order is canceled.
orderProductItem.status_changed	Order Product Item	status_changed	Triggered when an individual product item's status changes.
product.created	Product	created	Triggered when a new product is created.
product.updated	Product	updated	Triggered when a product is updated.
product.deleted	Product	deleted	Triggered when a product is deleted.
design.created	Design	created	Triggered when a design is created.
design.rendering_failed	Design	rendering_failed	Triggered when design rendering fails.
design.updated	Design	updated	Triggered when a design is updated.
design.deleted	Design	deleted	Triggered when a design is deleted.
generatedMedia.rendered	GeneratedMedia	rendered	Triggered when a rendering-task for the Mockup-Factory is completed.

How to Register a Webhook URL

To register a webhook, send a POST request to the /webhooks endpoint with the following parameters:

Webhook Parameters

Parameter	Type	Required	Description
resource	string	Yes	The entity the webhook listens to (e.g., "Order", "Product").
action	string	Yes	The event type (e.g., "created", "updated").
types	array	Yes	An array of webhook event keys (e.g., ["order.created", "product.updated"]).
url	string	Yes	The endpoint where the webhook request will be sent.
secret	string	No	A secret key for verifying request signatures.
signature_header	string	No	Defines the header field used for webhook signatures (default: "Signature").
is_active	boolean	No	Specifies whether the webhook is active (true) or not (false).

Example: Register a Webhook for New Orders

{
  "resource": "Order",
  "action": "created",
  "url": "https://yourserver.com/api/webhook-listener"
}

This webhook will send a POST request to https://yourserver.com/api/webhook-listener whenever a new order is created.

Receiving Webhooks

When is a Webhook Considered Successfully Delivered?

A webhook is successfully delivered when your server responds with an HTTP 2xx status code (e.g., 200 OK, 204 No Content).

If your server does not respond with a 2xx status, Shirtigo will retry sending the webhook.

How Are Failed Webhook Deliveries Handled?

Webhook retries follow an exponential backoff strategy:

1. If the webhook fails, the system waits before retrying.
2. The waiting time increases after each failed attempt.
3. After five failed attempts, the webhook is disabled and no further attempts are made.

Tip: Ensure your webhook handler responds quickly and always returns a 200 OK status.

How to Verify That a Webhook is Sent by Shirtigo Cockpit

Each webhook request includes a SHA-256 signature in the request header (X-Shirtigo-Signature), which you can validate.

Example: Verifying Webhook Signature (Node.js)

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const hash = crypto.createHmac('sha256', secret)
                     .update(JSON.stringify(payload))
                     .digest('hex');
  return hash === signature;
}

How to Test a Webhook

You can test webhooks before integrating them into production.

1. Using the Test Endpoint

Send a POST request to /webhooks/{id}/test with a valid resource_id:

{
  "resource_id": "CXY563"
}

This simulates a real event, but the payload will contain "mode": "testing".

2. Using a Webhook Testing Service

Use tools like Webhook.site to inspect real-time webhook requests.

3. Using cURL for Manual Testing

curl -X POST https://yourserver.com/webhook-endpoint \
     -H "Content-Type: application/json" \
     -d '{"event":"order.created","order_reference":"123456"}'

Conclusion

This documentation covers both the status information available in the Shirtigo Cockpit system and how to use webhooks to receive real-time updates. By understanding the various status types and properly configuring webhooks, you can effectively track orders and automate your workflows.