Fabrixa Integration API Reference

To access the Integration API, authenticate your requests using both an Application Access Token and an Application Key:

Authorization Header

Authorization: Bearer APPLICATION_ACCESS_TOKEN

Application Key Header

X-Application-Key: APPLICATION_KEY

Example cURL Command

curl -X 'GET' \
  'https://api.fabrixa.com/v2/integration/ping' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer APPLICATION_ACCESS_TOKEN' \
  -H 'X-Application-Key: APPLICATION_KEY'

Replace APPLICATION_ACCESS_TOKEN with your actual access token and APPLICATION_KEY with your actual application key.

The Integration API endpoints are organized by resource type and follow the RESTful architectural style. Each endpoint represents a resource, and actions on these resources are performed using standard HTTP methods.

All Integration API requests and responses are in JSON format, providing a consistent and easy-to-use interface for interacting with the API.

For full details on every endpoint, including request and response examples, see our Swagger documentation.

Response Format

All endpoints return data in a standardized format with these objects:

{
  "links": {
    "self": "https://api.fabrixa.com/v2/integration/products",
    "first_page": "https://api.fabrixa.com/v2/integration/products?page=1",
    "last_page": "https://api.fabrixa.com/v2/integration/products?page=2",
    "next_page": "https://api.fabrixa.com/v2/integration/products?page=2",
    "prev_page": null
  },
  "meta": {
    "total": 2,
    "current_page": 1,
    "per_page": 10
  },
  "data": [
    {
      "id": 1,
      "name": "Product 1",
      "description": "Description of Product 1"
    },
    {
      "id": 2,
      "name": "Product 2",
      "description": "Description of Product 2"
    }
  ]
}

Description of Response Objects

All API requests return HTTP status codes that provide insight into the response.

Error Response Body

An example of an error response body:

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/ping"
    },
    "meta": [],
    "errors": {
        "messages": [
            "Application Key is not specified."
        ]
    }
}

errors contains details about what failed. The messages array lists error descriptions. For a Bad Request, you will receive the names of the fields that failed validation.

The Integration API supports a limit of 30 requests per application per minute.

If you exceed this limit you will receive a 429 Too Many Requests response.

All Integration API responses include the X-RateLimit-Remaining header, how many requests the client can still make, and the X-RateLimit-Limit header, the total allowed per minute.

Sandbox mode lets you test your integration end to end before any real order is produced or charged. It applies to your entire account: orders from every sales channel, including the Integration API and connected Shopify and WooCommerce stores, are not produced and not charged to your balance. Your account is in sandbox mode while its status is Pending Activation.

In sandbox mode you can:

• connect your Shopify or WooCommerce store, or create an Integration API channel;
• add products and check prices and shipping estimates;
• import, create, update and cancel orders;
• see that none of these orders is produced or charged to your balance;
• verify webhook delivery and signatures.

To test orders, add products from the Fabrixa catalog: open a product, click Sell this and choose variants and designs. They then appear under My products.

To switch your account to sandbox mode, open the Platform, go to Settings → Company → Sandbox mode and click Switch to sandbox mode. You can also enable it when you add a new sales channel, including an Integration API channel, or email support@fabrixa.com and we will switch your account to sandbox mode for you. Sandbox mode is available to active accounts only.

When you are ready, activate your account yourself in the Platform under Settings → Company → Sandbox mode. You can also email support@fabrixa.com and we will activate it for you. Your connected stores and API credentials keep working, so nothing needs to be reconfigured.

Once activated, all new orders go to production and are charged to your balance. Orders created before activation remain test orders: they are never produced or charged, even after activation.

The catalog is everything Fabrixa produces. Your products are the catalog products you have added to your Fabrixa account, under your own names, descriptions, images and SKUs. An order row names a product variant - one size or version of a product - by its sku or variant_id: a variant of one of your products, or a catalog variant ordered directly.

To list the products Fabrixa produces, send a GET request to https://api.fabrixa.com/v2/integration/catalog/products with your credentials. It lists the active products that have a variant a printing partner currently produces, and only those variants, each with its SKU, selling price, dimensions and option values.

Query Parameters

Sample Request

curl -X 'GET' \
  'https://api.fabrixa.com/v2/integration/catalog/products?category_id=19&limit=10' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer APPLICATION_ACCESS_TOKEN' \
  -H 'X-Application-Key: APPLICATION_KEY'

Sample Response

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/catalog/products",
        "first_page": "https://api.fabrixa.com/v2/integration/catalog/products?page=1",
        "last_page": "https://api.fabrixa.com/v2/integration/catalog/products?page=1",
        "next_page": null,
        "prev_page": null
    },
    "meta": {
        "total": 1,
        "current_page": 1,
        "per_page": 10
    },
    "data": [
        {
            "id": 1305,
            "name": "Duvet Cover",
            "subtitle": "Duvet Cover with a pillow",
            "description": "
Soft personalized duvet cover.
",
            "slug": "duvet-cover",
            "code": "DUVET-001",
            "HS_code": "63023100",
            "created_at": "2024-08-16T09:32:07.000000Z",
            "updated_at": "2024-08-16T09:38:50.000000Z",
            "is_sellable": true,
            "variants_min_selling_price": "29.95",
            "variants_max_selling_price": "49.95",
            "type": {
                "id": 5,
                "name": "Duvet cover"
            },
            "status": {
                "id": 2,
                "name": "Active"
            },
            "categories": [
                {
                    "id": 19,
                    "name": "Duvet covers",
                    "description": "Personalized duvet covers",
                    "parent_category": {
                        "id": 8,
                        "name": "Bedroom",
                        "description": "Bedroom products"
                    }
                }
            ],
            "images": [
                {
                    "id": 5566,
                    "url": "https://storage.googleapis.com/example/catalog/duvet-cover.jpg",
                    "is_main": true,
                    "created_at": "2024-08-16T09:32:07.000000Z",
                    "screen_type_size": "large",
                    "sort_number": 1
                }
            ],
            "variants": [
                {
                    "id": 2705,
                    "name": "Duvet Cover",
                    "subtitle": "140x200",
                    "description": null,
                    "SKU": "COT864311",
                    "selling_price": "29.95",
                    "width": "140.00",
                    "height": "200.00",
                    "length": "2.00",
                    "weight": "1.20",
                    "created_at": "2024-08-06T11:23:44.000000Z",
                    "updated_at": "2024-08-16T09:36:37.000000Z",
                    "options": [
                        {
                            "id": 151,
                            "name": "Duvet Size",
                            "values": [
                                {
                                    "id": 471,
                                    "value": "140x200"
                                }
                            ]
                        }
                    ]
                },
                {
                    "id": 2708,
                    "name": "Duvet Cover",
                    "subtitle": "200x220",
                    "description": null,
                    "SKU": "COT864314",
                    "selling_price": "49.95",
                    "width": "200.00",
                    "height": "220.00",
                    "length": "2.00",
                    "weight": "1.80",
                    "created_at": "2024-08-06T11:23:44.000000Z",
                    "updated_at": "2024-08-16T09:37:11.000000Z",
                    "options": [
                        {
                            "id": 151,
                            "name": "Duvet Size",
                            "values": [
                                {
                                    "id": 474,
                                    "value": "200x220"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

Response Fields

To list the categories the catalog is organised in, send a GET request to https://api.fabrixa.com/v2/integration/catalog/categories with your credentials. The response holds the top-level categories, each with its sub-categories nested in sub_categories and the number of catalog products it holds in products_count. Pass a category's id as category_id when browsing the catalog, or a top-level category's id as parent_category_id to get the products of all its sub-categories at once.

Query Parameters

Sample Request

curl -X 'GET' \
  'https://api.fabrixa.com/v2/integration/catalog/categories?with_products_only=true' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer APPLICATION_ACCESS_TOKEN' \
  -H 'X-Application-Key: APPLICATION_KEY'

Sample Response

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/catalog/categories"
    },
    "meta": {
        "total": 1
    },
    "data": [
        {
            "id": 8,
            "name": "Bedroom",
            "description": "Bedroom products",
            "sort_number": 1,
            "slug": "bedroom",
            "products_count": 12,
            "sub_categories": [
                {
                    "id": 19,
                    "name": "Duvet covers",
                    "description": "Personalized duvet covers",
                    "sort_number": 1,
                    "slug": "duvet-covers",
                    "products_count": 7,
                    "images": [],
                    "sub_categories": []
                },
                {
                    "id": 20,
                    "name": "Pillows",
                    "description": "Personalized pillows and pillowcases",
                    "sort_number": 2,
                    "slug": "pillows",
                    "products_count": 4,
                    "images": [],
                    "sub_categories": []
                }
            ],
            "parent_category": null,
            "images": [
                {
                    "id": 781,
                    "url": "https://storage.googleapis.com/example/catalog/bedroom.jpg",
                    "is_main": true,
                    "created_at": "2024-08-16T09:32:07.000000Z",
                    "screen_type_size": "large",
                    "sort_number": 1
                }
            ]
        }
    ]
}

To list the products in your account, send a GET request to https://api.fabrixa.com/v2/integration/products with your credentials. Your products are the catalog products you added to your Fabrixa account: they carry the names, descriptions and images you gave them there, and their variants the SKU values you chose. Only active products are listed, ten per page unless you pass limit.

Query Parameters

Sample Request

curl -X 'GET' \
  'https://api.fabrixa.com/v2/integration/products?search=duvet' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer APPLICATION_ACCESS_TOKEN' \
  -H 'X-Application-Key: APPLICATION_KEY'

Sample Response

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/products",
        "first_page": "https://api.fabrixa.com/v2/integration/products?page=1",
        "last_page": "https://api.fabrixa.com/v2/integration/products?page=1",
        "next_page": null,
        "prev_page": null
    },
    "meta": {
        "total": 1,
        "current_page": 1,
        "per_page": 10
    },
    "data": [
        {
            "id": 5321,
            "name": "Dreamy Duvet Cover",
            "subtitle": "Duvet cover with a matching pillowcase",
            "description": "
Our personalized duvet cover, printed on soft cotton sateen.
",
            "slug": "dreamy-duvet-cover",
            "width": "50.00",
            "height": "50.00",
            "length": "20.00",
            "weight": "100.00",
            "created_at": "2025-03-04T10:12:40.000000Z",
            "updated_at": "2025-03-04T10:15:02.000000Z",
            "type": {
                "id": 5,
                "name": "Duvet cover",
                "description": "Duvet cover with pillow"
            },
            "available_options": [
                {
                    "id": 151,
                    "name": "Duvet Size",
                    "values": [
                        {
                            "id": 471,
                            "value": "140x200"
                        },
                        {
                            "id": 474,
                            "value": "200x220"
                        }
                    ]
                }
            ],
            "categories": [
                {
                    "id": 912,
                    "name": "Bedding"
                }
            ],
            "collections": [
                {
                    "id": 77,
                    "name": "Spring 2025"
                }
            ],
            "images": [
                {
                    "id": 48120,
                    "is_main": true,
                    "image_size": "1200x1200",
                    "url": "https://storage.googleapis.com/example/shop/dreamy-duvet-cover.jpg",
                    "screen_type_size": "large",
                    "sort_number": 1
                }
            ],
            "variants": [
                {
                    "id": 32323,
                    "name": "Dreamy Duvet Cover",
                    "subtitle": "140x200",
                    "description": null,
                    "SKU": "DDC-140200",
                    "created_at": "2025-03-04T10:12:41.000000Z",
                    "updated_at": "2025-03-04T10:12:41.000000Z",
                    "options": [
                        {
                            "id": 151,
                            "name": "Duvet Size",
                            "values": [
                                {
                                    "id": 471,
                                    "value": "140x200"
                                }
                            ]
                        }
                    ],
                    "images": [],
                    "available_source_types": ["duvet", "pillow", "pillow-back"],
                    "required_source_types": ["duvet", "pillow"]
                },
                {
                    "id": 32326,
                    "name": "Dreamy Duvet Cover",
                    "subtitle": "200x220",
                    "description": null,
                    "SKU": "DDC-200220",
                    "created_at": "2025-03-04T10:12:41.000000Z",
                    "updated_at": "2025-03-04T10:12:41.000000Z",
                    "options": [
                        {
                            "id": 151,
                            "name": "Duvet Size",
                            "values": [
                                {
                                    "id": 474,
                                    "value": "200x220"
                                }
                            ]
                        }
                    ],
                    "images": [],
                    "available_source_types": ["duvet", "pillow", "pillow-back"],
                    "required_source_types": ["duvet", "pillow"]
                }
            ]
        }
    ]
}

To read one product, send a GET request to https://api.fabrixa.com/v2/integration/products/{product_id}, where {product_id} is its id. The response carries the same fields as the list. A product that is not in your account, even a catalog one, answers 404 Not Found with the message Product not found.

Response Fields

A variant is one orderable version of a product - one size, one colour - and what an order row names, by sku or by variant_id. To read a variant of one of your products, send a GET request to https://api.fabrixa.com/v2/integration/variants/{variant_id}, where {variant_id} is its id. A variant of a product that is not in your account answers 404 Not Found with the message Variant not found.

Sample Request

curl -X 'GET' \
  'https://api.fabrixa.com/v2/integration/variants/32323' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer APPLICATION_ACCESS_TOKEN' \
  -H 'X-Application-Key: APPLICATION_KEY'

Sample Response

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/variants/32323"
    },
    "meta": [],
    "data": {
        "id": 32323,
        "name": "Dreamy Duvet Cover",
        "subtitle": "140x200",
        "description": null,
        "SKU": "DDC-140200",
        "created_at": "2025-03-04T10:12:41.000000Z",
        "updated_at": "2025-03-04T10:12:41.000000Z",
        "width": "140.00",
        "height": "200.00",
        "length": "2.00",
        "weight": "1.20",
        "options": [
            {
                "id": 151,
                "name": "Duvet Size",
                "values": [
                    {
                        "id": 471,
                        "value": "140x200"
                    }
                ]
            }
        ],
        "images": [],
        "product": {
            "id": 5321,
            "name": "Dreamy Duvet Cover",
            "subtitle": "Duvet cover with a matching pillowcase",
            "description": "
Our personalized duvet cover, printed on soft cotton sateen.
",
            "description2": null,
            "slug": "dreamy-duvet-cover",
            "created_at": "2025-03-04T10:12:40.000000Z",
            "updated_at": "2025-03-04T10:15:02.000000Z"
        },
        "available_source_types": ["duvet", "pillow", "pillow-back"],
        "required_source_types": ["duvet", "pillow"]
    }
}

Response Fields

An order row for this variant, with a PDF whose pages are its layers:

"rows": [
    {
        "sku": "DDC-140200",
        "quantity": 1,
        "sources": [
            {
                "type": "file",
                "url": "https://samples-files.com/samples/duvet-cover.pdf"
            }
        ]
    }
]

Which Variants Can Be Ordered

Create orders in Fabrixa from your own storefront or platform, attach the required print files, and follow each item as it moves through fulfilment.

To create an order via the Fabrixa Integration API, send a POST request to https://api.fabrixa.com/v2/integration/orders. The request body must include:

Request Body Structure

Sample Request

{
  "number": "NL2024010201",
  "comments": "Customer agrees with a low resolution file.",
  "purchased_at": "2024-06-26 21:12:22",
  "client_ip": "127.0.0.1",
  "client_user_agent": "Mozilla",
  "rows": [
    {
      "variant_id": 2705,
      "quantity": 1,
      "client_barcode": "1234567890",
      "sources": [
        {
          "type": "file",
          "url": "https://samples-files.com/samples/sample.pdf"
        }
      ]
    }
  ],
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "3VJtP@example.com",
    "phone": "0612345678"
  },
  "shipping_address": {
    "address": "Voorbeeldstraat",
    "address2": "17",
    "city": "Amsterdam",
    "country_code": "NL",
    "country": "Netherlands",
    "postal_code": "1012 AB",
    "state": "North Holland",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "0612345678"
  },
  "shipping_label": {
    "method_name": "Post NL",
    "tracking_number": "3SABCD1234567",
    "tracking_url": "https://postnl.nl/tracktrace/3SABCD1234567",
    "label_pdf_url": "https://api.fabrixa.com/storage/8966630826422f36d822f91680012141.pdf",
    "date_created": "2024-01-01 00:00:00"
  }
}

Sample Response

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/orders"
    },
    "meta": [],
    "data": {
        "id": 20338,
        "number": "NL2024010201",
        "comments": "Customer agrees with a low resolution file.",
        "is_archived": false,
        "status": "imported",
        "fulfillment_status": "unfulfilled",
        "purchased_at": "2024-06-26T21:12:22.000000Z",
        "created_at": "2024-06-26T21:15:03.000000Z",
        "updated_at": "2024-06-26T21:15:04.000000Z",
        "rows": [
            {
                "id": 41600,
                "quantity": 1,
                "client_barcode": "1234567890",
                "fulfillment_status": "unfulfilled",
                "variant": {
                    "id": 2705,
                    "name": "Duvet Cover",
                    "subtitle": "140x200",
                    "SKU": "COT864311",
                    "product": {
                        "id": 1305,
                        "name": "Duvet Cover",
                        "subtitle": "Duvet Cover with a pillow"
                    }
                },
                "sources": [
                    {
                        "type": "file",
                        "url": "https://samples-files.com/samples/sample.pdf",
                        "properties": null
                    }
                ]
            }
        ],
        "shipments": [],
        "customer": {
            "email": "3VJtP@example.com",
            "first_name": "John",
            "last_name": "Doe",
            "phone": "0612345678"
        },
        "shipping_address": {
            "address": "Voorbeeldstraat",
            "address2": "17",
            "address3": null,
            "city": "Amsterdam",
            "country": "Netherlands",
            "country_code": "NL",
            "company": null,
            "first_name": "John",
            "last_name": "Doe",
            "phone": "0612345678",
            "state": "North Holland",
            "postal_code": "1012 AB"
        }
    }
}

To update an order, send a PATCH request to https://api.fabrixa.com/v2/integration/orders/{order_id}, where {order_id} is the Fabrixa order id. Only the fields you send are changed, and the order status stays as it is. The response contains the updated order. You can change:

Sample Request

{
  "comments": "Deliver to the neighbours if nobody is home.",
  "shipping_address": {
    "address": "Voorbeeldstraat",
    "address2": "19",
    "city": "Amsterdam",
    "country_code": "NL",
    "country": "Netherlands",
    "postal_code": "1012 AB",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "0612345678"
  }
}

Sample Response

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/orders/20338"
    },
    "meta": [],
    "data": {
        "id": 20338,
        "number": "NL2024010201",
        "comments": "Deliver to the neighbours if nobody is home.",
        "is_archived": false,
        "status": "imported",
        "fulfillment_status": "unfulfilled",
        "purchased_at": "2024-06-26T21:12:22.000000Z",
        "created_at": "2024-06-26T21:15:03.000000Z",
        "updated_at": "2024-06-27T09:41:18.000000Z",
        "rows": [
            {
                "id": 41600,
                "quantity": 1,
                "client_barcode": "1234567890",
                "fulfillment_status": "unfulfilled",
                "variant": {
                    "id": 2705,
                    "name": "Duvet Cover",
                    "subtitle": "140x200",
                    "SKU": "COT864311",
                    "product": {
                        "id": 1305,
                        "name": "Duvet Cover",
                        "subtitle": "Duvet Cover with a pillow"
                    }
                },
                "sources": [
                    {
                        "type": "file",
                        "url": "https://samples-files.com/samples/sample.pdf",
                        "properties": null
                    }
                ]
            }
        ],
        "shipments": [],
        "customer": {
            "email": "3VJtP@example.com",
            "first_name": "John",
            "last_name": "Doe",
            "phone": "0612345678"
        },
        "shipping_address": {
            "address": "Voorbeeldstraat",
            "address2": "19",
            "address3": null,
            "city": "Amsterdam",
            "country": "Netherlands",
            "country_code": "NL",
            "company": null,
            "first_name": "John",
            "last_name": "Doe",
            "phone": "0612345678",
            "state": "North Holland",
            "postal_code": "1012 AB"
        }
    }
}

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/orders/20338"
    },
    "meta": [],
    "errors": {
        "rows": [
            "Order rows cannot be changed. Cancel the order and create a new one."
        ]
    }
}

To cancel an order, send a POST request without a body to https://api.fabrixa.com/v2/integration/orders/{order_id}/cancel, where {order_id} is the Fabrixa order id (the numeric id field of the order), not your order number. The response contains the order with the status canceled, and an order.updated webhook is sent.

Sample Response

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/orders/20338/cancel"
    },
    "meta": [],
    "data": {
        "id": 20338,
        "number": "NL2024010201",
        "comments": "Customer agrees with a low resolution file.",
        "is_archived": false,
        "status": "canceled",
        "fulfillment_status": "unfulfilled",
        "purchased_at": "2024-06-26T21:12:22.000000Z",
        "created_at": "2024-06-26T21:15:03.000000Z",
        "updated_at": "2024-06-27T10:02:45.000000Z",
        "rows": [
            {
                "id": 41600,
                "quantity": 1,
                "client_barcode": "1234567890",
                "fulfillment_status": "unfulfilled",
                "variant": {
                    "id": 2705,
                    "name": "Duvet Cover",
                    "subtitle": "140x200",
                    "SKU": "COT864311",
                    "product": {
                        "id": 1305,
                        "name": "Duvet Cover",
                        "subtitle": "Duvet Cover with a pillow"
                    }
                },
                "sources": [
                    {
                        "type": "file",
                        "url": "https://samples-files.com/samples/sample.pdf",
                        "properties": null
                    }
                ]
            }
        ],
        "shipments": [],
        "customer": {
            "email": "3VJtP@example.com",
            "first_name": "John",
            "last_name": "Doe",
            "phone": "0612345678"
        },
        "shipping_address": {
            "address": "Voorbeeldstraat",
            "address2": "17",
            "address3": null,
            "city": "Amsterdam",
            "country": "Netherlands",
            "country_code": "NL",
            "company": null,
            "first_name": "John",
            "last_name": "Doe",
            "phone": "0612345678",
            "state": "North Holland",
            "postal_code": "1012 AB"
        }
    }
}

If the order cannot be canceled, the API responds with 412 Precondition Failed and a message explaining why: its current status does not allow it (the status is named in the message), or production has already started.

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/orders/20338/cancel"
    },
    "meta": [],
    "errors": {
        "messages": [
            "This order cannot be canceled in its current status (ready for shipping)."
        ]
    }
}

An order is tracked with three statuses: the order status, its production status fulfillment_status and the status of each shipment in shipments. Every change is sent in the order.updated webhook and returned by GET /orders/{order_id}.

Order Statuses

The status of an order, in the order it is reached:

• imported - the order has been received through the API. Every order starts here.
• on hold - your balance does not cover the cost of the order. Once it is topped up, the order returns to imported and continues.
• accepted - the order has been accepted and is sent to production.
• completed (final) - all items have been produced.
• canceled (final) - the order has been canceled. This is possible while it is imported, accepted or on hold and production has not started yet.

Fulfillment Statuses

The fulfillment_status of an order and of each order row, in the order it is reached. It only moves forward, never back:

• unfulfilled - production has not started.
• scheduled - the order is planned in a production batch. From here on, it can no longer be canceled.
• processing - production is underway.
• partially fulfilled - some items are finished, the rest are still in production.
• fulfilled (final) - all items are finished. The order status then becomes completed.

An order as a whole is never rejected. A single item can be rejected in the quality check during production. It is then printed again: it returns to unfulfilled and goes through production once more, while the order keeps its status and continues once the item is finished.

Shipment Statuses

The status of each shipment in shipments, in the order it is reached:

• pending - the shipment is being prepared.
• registered - the label has been created with the carrier.
• collected - the carrier has picked up the parcel.
• in transit - the parcel is on its way.
• delivered (final) - the parcel has been delivered.

Exceptions:

• failed - the carrier reported a problem.
• returned (final) - the parcel was returned to us.
• canceled (final) - the shipment was canceled.

To get the fulfilment status for a specific order, send a GET request to https://api.fabrixa.com/v2/integration/orders/{order_id}/fulfillments. The response provides a list of fulfilments associated with the order, including each item status, product details, and production-step progress.

Sample Response

{
    "data": [
        {
            "id": 1499,
            "barcode": "1200004169200",
            "status": "unfulfilled",
            "created_at": "2024-08-19T12:38:59.000000Z",
            "updated_at": "2024-08-19T12:39:00.000000Z",
            "variant": {
                "id": 32327,
                "name": "Test iAPI blanket product",
                "subtitle": "100 x 150 cm",
                "SKU": "COF099191"
            },
            "product": {
                "id": 1306,
                "name": "Test iAPI blanket product",
                "subtitle": "Test iAPI blanket product"
            },
            "production_steps": [
                {
                    "id": 5,
                    "name": "Print duvet",
                    "description": "Printing the duvet according to the specified design and dimensions.",
                    "status": {
                        "value": "pending",
                        "notes": null,
                        "updated_at": null
                    }
                },
                {
                    "id": 6,
                    "name": "Print pillow",
                    "description": "Printing the pillow cover with the assigned design.",
                    "status": {
                        "value": "pending",
                        "notes": null,
                        "updated_at": null
                    }
                }
            ]
        }
    ]
}

The response includes a list of fulfilments, each providing:

Each fulfilment record corresponds to a specific product or product variant within the order, and each copy of the product in the order has its own fulfilment record - every item is tracked individually throughout production.

If no fulfilments are returned for an order, the order has not yet entered the processing stage.

When including source files in your order, ensure they meet the following requirements:

"sources": [
    {
        "type": "file",
        "url": "https://samples-files.com/samples/source.pdf"
    }
]

PDF Requirements and Page Order

The order of pages in the PDF is important. Pages are matched to product layers by position, and the expected page order depends on the product type. Make sure the pages in your PDF follow the correct layer sequence for the product you are submitting.

Important: each PDF page must match the required dimensions for its product layer and be oriented correctly. Place the artwork so the top of the design aligns with the top of the page. Incorrect page size or orientation may cause scaling, rotation, or alignment issues in production.

Know what shipping an order will cost and how long it will be under way before you place it, priced by the same rules Fabrixa applies to the order itself.

To find out which countries a product variant can be shipped to, send a GET request to https://api.fabrixa.com/v2/integration/shipping/countries with your credentials. The list holds the countries the location producing the variant has a shipping rate to, for a shipping package the variant can be packed into, sorted by name. A country that is not listed has no shipping rate for the variant.

Query Parameters

Sample Request

curl -X 'GET' \
  'https://api.fabrixa.com/v2/integration/shipping/countries?sku=DDC-140200' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer APPLICATION_ACCESS_TOKEN' \
  -H 'X-Application-Key: APPLICATION_KEY'

Sample Response

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/shipping/countries"
    },
    "meta": {
        "total": 2
    },
    "data": [
        {
            "code": "BE",
            "name": "Belgium",
            "min_shipping_price": "7.75",
            "max_shipping_price": "9.85",
            "currency": "EUR",
            "min_eta_days": 1,
            "max_eta_days": 2
        },
        {
            "code": "NL",
            "name": "Netherlands",
            "min_shipping_price": "6.70",
            "max_shipping_price": "8.40",
            "currency": "EUR",
            "min_eta_days": 1,
            "max_eta_days": 1
        }
    ]
}

Response Fields

To find out what shipping a product variant would cost and how long it would be under way, send a GET request to https://api.fabrixa.com/v2/integration/shipping/estimate with your credentials. The estimate follows the rules an order is priced by: the units are packed into the shipping packages of the location producing the variant, and each package is priced along the route from that location to the destination country. Nothing is ordered or reserved, and an order is priced when it is placed, so its shipping can differ if the rates change in between.

Query Parameters

Sample Request

curl -X 'GET' \
  'https://api.fabrixa.com/v2/integration/shipping/estimate?sku=DDC-140200&country_code=NL&quantity=2' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer APPLICATION_ACCESS_TOKEN' \
  -H 'X-Application-Key: APPLICATION_KEY'

Sample Response

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/shipping/estimate"
    },
    "meta": [],
    "data": {
        "variant_id": 32323,
        "sku": "DDC-140200",
        "quantity": 2,
        "country_code": "NL",
        "origin_country": {
            "code": "PT",
            "name": "Portugal"
        },
        "packages_count": 1,
        "packages": [
            {
                "package_type": "Small Box",
                "length": 30,
                "width": 20,
                "height": 10,
                "quantity": 1,
                "price": "7.45",
                "eta_days": 3
            }
        ],
        "shipping_price": "7.45",
        "currency": "EUR",
        "eta_days": 3
    }
}

Response Fields

A request that fails validation is answered with 400 Bad Request and the reason for each field, with the same messages as an order row, for example The variant not found. When no shipping package can carry the units, the answer is 400 Bad Request with the message No shipping package can carry the variant.

Fabrixa Studio is a tool that lets users seamlessly customize and personalize products in real time with an intuitive interface where users can create or upload their own designs.

Fabrixa Studio is ideal for businesses offering custom products - enabling customers to visualize their designs before finalizing orders.

You can embed Fabrixa Studio into your website using an iframe. This enables your customers to personalize products directly on your site during checkout.

Example iframe for embedding Fabrixa Studio:

<iframe id="fabrixa-studio"
    src="https://studio.fabrixa.com?application_key={application_key}&sku={product_sku}&cart_item_key={cart_item_key}"
    name="FabrixaStudio"
    scrolling="no"
    frameborder="1"
    width="100%"
    height="100%"
    allowfullscreen="">
</iframe>

Replace the values for product_sku, cart_item_key, and application_key with your dynamic values.

• application_key - unique key for authenticating to the Integration API.
• product_sku - the SKU of the product variant, retrieved from the Integration API.
• cart_item_key - a unique value from the embedding platform identifying the cart item associated with the product. Used to save the user customizations; during order creation it identifies the saved customizations and assigns them to the order. See example below.
• locale (optional) - the language of Studio's interface and of its error messages, e.g. de_DE or de. Without it, Studio opens in the shopper's browser language if it is supported, otherwise in English.

Studio's header shows the product's name as it is in your shop - the same title your customers see - with the chosen variant's options under it. It is your shop's own copy of the product, so a name you edit in Fabrixa shows in Studio too; locale does not translate it.

Request to Create an Order with cart_item_key

{
  "number": "NL2024010201",
  "purchased_at": "2024-06-26 21:12:22",
  "client_ip": "127.0.0.1",
  "client_user_agent": "Mozilla",
  "rows": [
    {
      "sku": "SB796162",
      "quantity": 1,
      "cart_item_key": "0cb76770-de2d-4524-aa48-47b6e5f0d8a5"
    }
  ],
  "customer": {
    "...": "..."
  },
  "shipping_address": {
    "...": "..."
  },
  "shipping_label": {
    "...": "..."
  }
}

When the Add to Cart button is clicked inside the iframe, the following command is executed:

window.parent.postMessage('customizationFinished', '*');

Similarly, when the Back button is clicked:

window.parent.postMessage('closeButtonClicked', '*');

The postMessage method facilitates cross-origin communication between the iframe and its parent window, allowing it to notify the parent about specific user actions.

The first argument of postMessage is the data you want to send. The string 'customizationFinished' indicates the user has finalized customization and is adding the product to the cart. 'closeButtonClicked' indicates the user has chosen to go back.

In the parent window, listen for these messages using the message event listener:

window.addEventListener('message', function(event) {
    if (event.origin === 'https://studio.fabrixa.com') {
        if (event.data === 'customizationFinished') {
            // Handle the Add to Cart event
            console.log('Customization finished and item can be added to cart.');
        } else if (event.data === 'closeButtonClicked') {
            // Handle the Back button event
            console.log('Back button clicked.');
        }
    }
});

Always check the origin of incoming messages to ensure they come from a trusted source. Depending on the message received, perform the necessary actions - update the user interface, process the cart, etc. Validating origin is crucial for security - it prevents unauthorized scripts from interacting with your application.

After customization is completed, display the final design using the preview URL below. This URL returns an image of the customized product, suitable as the src value in an <img> tag. Ideal for showing the customized product in your cart, order summary, or anywhere in your shop interface.

https://api.fabrixa.com/v2/studio/customizations/{CART_ITEM_KEY}/preview?Application-Key={APPLICATION_KEY}

Replace {CART_ITEM_KEY} with the actual cart item key and {APPLICATION_KEY} with your valid application key.

Example usage in an image tag:

<img
    src="https://api.fabrixa.com/v2/studio/customizations/{CART_ITEM_KEY}/preview?Application-Key={APPLICATION_KEY}"
    alt="Customized Product Preview"
    style="max-width: 100%; height: auto;" />

Webhooks are used by Fabrixa to notify your system about real-time events - order updates or creations. When an event occurs, Fabrixa sends a webhook to your server containing the relevant information. Your server must expose a public POST endpoint to handle incoming webhooks.

The webhook request includes the following headers to help you identify and validate the incoming request:

{
  "content-type": "application/json",
  "user-agent": "Fabrixa/2.0 (+https://api.fabrixa.com/docs/integration#webhooks; webhook)",
  "x-webhook-signature": "YmEwNjBhMGMyMzE3ZWQ5NGQ5NDYwOGVhNzNhMjQ4M2MyODZkZmI3NTQ1YzYxYjdkMzNhZjgzYzBmMTkxYTAxMw==",
  "x-webhook-topic": "order.updated"
}

Header Breakdown

• content-type - always set to application/json for webhooks.
• x-webhook-signature - the HMAC-SHA256 signature for request verification.
• x-webhook-topic - the event type or topic of the webhook. For example:
  • order.created - triggered when a new order is created.
  • order.updated - triggered when an existing order is updated.

Webhooks are sent with the User-Agent Fabrixa/2.0 (+https://api.fabrixa.com/docs/integration#webhooks; webhook); if your endpoint filters automated traffic, allow it. To be sure a request comes from Fabrixa, verify x-webhook-signature.

Fabrixa webhooks notify your system of changes in order status or activity. Each webhook is triggered by a specific x-webhook-topic value. Currently supported topics:

An example of the payload sent with the webhook. This payload represents an order update:

{
  "id": 23069,
  "number": "1250211835",
  "comments": null,
  "is_archived": false,
  "status": "accepted",
  "fulfillment_status": "fulfilled",
  "purchased_at": "2025-04-17T16:17:21.000000Z",
  "created_at": "2025-04-17T16:17:23.000000Z",
  "updated_at": "2025-04-18T07:43:52.000000Z",
  "rows": [
    {
      "id": 27954,
      "quantity": 1,
      "client_barcode": "1250211835",
      "fulfillment_status": "fulfilled",
      "variant": {
        "id": 293457,
        "name": "Sherpa fleece deken",
        "subtitle": "100x150",
        "SKU": "SFD787231",
        "product": {
          "id": 5319,
          "name": "Sherpa fleece deken",
          "subtitle": "Sherpa fleece deken"
        }
      },
      "sources": [
        {
          "type": "print",
          "url": "https://storage.googleapis.com/fabrixa-api/storage/99b10aaa-df4d-47e4-9bc9-b1d6a785df4c/orders/merchandise-sources/120002795400.pdf",
          "properties": {
            "fill_style": "contain"
          }
        }
      ]
    }
  ],
  "shipments": [
    {
      "id": 4182,
      "carrier": "PostNL",
      "method": "Standard",
      "status": "registered",
      "tracking_number": "3SABCD1234567",
      "tracking_url": "https://jouw.postnl.nl/track-and-trace/3SABCD1234567-NL-1012AB",
      "packages": [
        {
          "tracking_number": "3SABCD1234567",
          "tracking_url": "https://jouw.postnl.nl/track-and-trace/3SABCD1234567-NL-1012AB"
        }
      ],
      "expected_delivery_date": "2025-04-22",
      "created_at": "2025-04-18T07:43:50.000000Z"
    }
  ]
}

Once the order ships, shipments lists each shipment with its carrier, shipping method, status (pending, registered, collected, in transit, delivered, failed, returned or canceled) and tracking: tracking_number and tracking_url, and the same for each package in packages when a shipment has several. An order.updated webhook is sent whenever a shipment's status or tracking changes, and GET /orders/{order_id} returns the same field.

To ensure the webhook request is authentic and untampered, verify the x-webhook-signature header. This involves recalculating the HMAC-SHA256 signature using the raw request payload and your secret key, then comparing it to the received signature.

Raw PHP Example

$payload = file_get_contents('php://input');
$yourSecret = 'your-secret-key';
$expectedSignature = base64_encode(hash_hmac('sha256', $payload, $yourSecret, true));
$receivedSignature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

if (!hash_equals($expectedSignature, $receivedSignature)) {
    http_response_code(403);
    exit('Invalid signature');
}

Laravel Example

public function handle(Request $request)
{
    $yourSecret = 'your-secret-key';
    $payload = $request->getContent();
    $expectedSignature = base64_encode(hash_hmac('sha256', $payload, $yourSecret, true));
    $receivedSignature = $request->header('x-webhook-signature');

    if (!hash_equals($expectedSignature, $receivedSignature)) {
        abort(403, 'Invalid signature');
    }

    // Continue processing...
}

Replace $yourSecret with your shared secret key. Always use hash_equals for comparing signatures to mitigate timing attacks.

Webhooks are disabled after 10 unsuccessful delivery attempts by default. If your endpoint returns an unsuccessful status such as 404 or any 5xx error, the webhook will retry for a total of 10 times. If it continues to return a non-2xx or non-3xx response code, it will be deactivated. Successful responses include:

• 2xx - indicates successful processing, e.g. 200 OK.
• 301 and 302 - redirection responses indicating the webhook has been successfully handled or forwarded.

We strongly recommend your endpoint returns a 200 OK status code as quickly as possible to acknowledge successful receipt of the webhook. While any 2xx or 3xx response is considered successful, 200 is the most commonly used and reliable.

To avoid delivery timeouts or retries, return 200 OK immediately and handle webhook payload processing asynchronously, for example via a background job or queue. If your endpoint takes too long to respond, it may be considered a failure even if the response is ultimately successful.

Responses with status codes in the 4xx or 5xx range, or timeouts, will trigger retries according to the retry mechanism.