Bulk Order Creation Guide

Overview

Endpoint

POST /api/accounts/{accountId}/orders/bulk

The Bulk Order Creation endpoint allows you to create multiple independent orders in a single API request. Each entry in orderRequests creates its own order.

This endpoint is ideal for bulk imports, batch order submissions, integration syncs, or catching up on orders after an interruption.

Note: The bulk endpoint uses the same order structure as the standard single-order endpoint and supports up to 1,000 independent orders per request.

Request

Each order should be included as a separate object within the orderRequests array.

Example Request

{
  "orderRequests": [
    {
      "customId": "1",
      "CustomIdIsUniqueKey": true,
      "orderItemGroups": [
        {
          "designData": {
            "artwork": [
              {
                "originalFileUrl": "https://stffe1prodncus.blob.core.windows.net/images/dev-test/Black Logo Mark.png",
                "physicalSize": {
                  "widthInches": 3.5,
                  "heightInches": 3.5
                },
                "printingMethod": "dtf",
                "printLocation": "front"
              }
            ]
          },
          "sku": "5771202750",
          "quantity": 1
        }
      ],
      "isTest": true,
      "shipments": [
        {
          "shippingAddress": {
            "name": "Jane Doe",
            "addressLine1": "100 Main St",
            "city": "Charleston",
            "state": "SC",
            "postalCode": "29403",
            "country": "US"
          },
          "shippingTier": "Standard"
        }
      ]
    },
    {
      "customId": "2",
      "CustomIdIsUniqueKey": true,
      "orderItemGroups": [
        {
          "designData": {
            "artwork": [
              {
                "originalFileUrl": "https://stffe1prodncus.blob.core.windows.net/images/dev-test/Black Logo Mark.png",
                "physicalSize": {
                  "widthInches": 3.5,
                  "heightInches": 3.5
                },
                "printingMethod": "dtf",
                "printLocation": "front"
              }
            ]
          },
          "sku": "5771202750",
          "quantity": 1
        }
      ],
      "isTest": true,
      "shipments": [
        {
          "shippingAddress": {
            "name": "Jane Doe",
            "addressLine1": "100 Main St",
            "city": "Charleston",
            "state": "SC",
            "postalCode": "29403",
            "country": "US"
          },
          "shippingTier": "Standard"
        }
      ]
    }
  ]
}

In this example, two independent test orders are submitted in a single request. Each order has its own customId, order items, design data, and shipment information.

Each item within orderRequests uses the same request structure as the standard single-order OrderRequest model.

Request Constraints

Maximum Orders Per Request

Up to 1,000 orders can be submitted in a single request.

Requests containing more than 1,000 orders will be rejected with:

TooManyOrderRequests

Minimum Orders Per Request

At least one order must be included in the request.

An empty or missing orderRequests array will be rejected with:

MissingOrderRequest

Campaign Validation

Every unique campaignId referenced within the batch must belong to the accountId used in the request.

If a referenced campaign does not belong to the account, the entire request will fail with:

CampaignInvalidForAccount

Per-Order Validation

Each order within the batch is normalized and validated using the same validation process as an order submitted through the standard single-order endpoint.

Each individual order must contain valid order, product, design, shipment, and other required information.

Deduplication Using CustomIdIsUniqueKey

The optional CustomIdIsUniqueKey field can be used to prevent duplicate orders when submitting or retrying a batch.

To enable duplicate protection for an order, include:

"CustomIdIsUniqueKey": true

When CustomIdIsUniqueKey is set to true, a customId must also be provided.

If customId is missing, the request will fail with:

MissingCustomId

Before creating the orders, the system checks for existing orders and pending order requests associated with the account that match the submitted customId values.

If an order with the same customId already exists, the order is not created again. Instead, the existing orderId is returned in the response.

Retrying a batch: This makes the bulk endpoint safe to retry. If a batch only partially succeeds, the same payload can be submitted again. Orders that already exist will be skipped, while orders that are still missing can be created.

Response

The response contains an OrderResponses array with an OrderId and CustomId for each order included in the request.

Example Response

{
  "OrderResponses": [
    {
      "OrderId": "abc123",
      "CustomId": "1"
    },
    {
      "OrderId": "def456",
      "CustomId": "2"
    }
  ]
}

The response can include:

• Newly created orders

• Existing orders identified through CustomIdIsUniqueKey deduplication

Each response item contains the corresponding OrderId and CustomId.

Processing

Newly created orders submitted through the bulk endpoint are grouped together and queued for processing as a batch.

Once queued, each order continues through validation, production, fulfillment, and shipping independently as a standard order.

Important: Orders are not combined into a single fulfillment order. Each entry in orderRequests remains its own independent order throughout the fulfillment process.