SwiftPOD
  1. Api
SwiftPOD
  • Api
    • Webhook
      • List Webhooks
      • Subscribe to Webhook
      • Unsubcribe to webhook
      • Webhook Notification - Order Status Change Example
      • Webhook Notification - Tracking Number Example
      • Webhook Notification - In Transit and Delivered Status Example
      • Webhook Notification - Stock Status Change Example
    • Orders
      GET
    • Create Order
      POST
    • Create Multiple Orders
      POST
    • Get Order
      GET
    • Update Order
      PUT
    • Update Order Status
      PUT
    • Cancel Order
      POST
    • Catalogs
      GET
  • Changelog
  1. Api

Create Order

POST
/v1/orders

Request

Header Params
Accept
string 
required
Example:
application/json
Body Params application/json
order_id
string 
required
A unique ID that you provide to track orders. Swiftpod will raise an error if you have any orders with the same order_id.
test_order
boolean 
optional
When the parameter is set to TRUE, the test order functionality is activated, specifically designed for testing the system's operation. This feature generates simulated order processes with distinct stages which are "new order", "in production", and "shipped" with fictitious tracking number. Test orders are not meant to be fulfilled or billed and can be conveniently monitored and tracked within our internal dashboard.
order_status
enum<string> 
optional
Default value: new_order
Allowed values:
draftnew_order
order_type
enum<integer> 
optional
Allowed values:
567
label_url
string 
optional
Required when order_type = 5. Supports file formats: PDF, PNG, JPG.
Sample link for tiktok orders: https://swiftpod.s3.us-west-1.amazonaws.com/demo/sample_label.usps.s4x6.pdf
line_items
array [object {7}] 
required
A list of line item objects, each containing information about an item in the order.
order_item_id
string 
required
A unique ID that you provide to track line items. We will raise an error if you have other line items with the same order_item_id.
sku
string 
required
SKU of the item variant to fulfill. You can find all available IDs for an item in the catalog.
name
string 
optional
Your product name
quantity
integer 
required
The number of items to fulfill. Must be 1 or greater.
print_files
array [object {2}] 
required
The recommended dimensions for the neck label are 2.5 x 2 inches (or approximately 750 x 600 pixels) at 300 dpi resolution, which provides high-quality printing results. Do not use when order_type = 7.
preview_files
array [object {2}] 
optional
production_config
enum<string> 
optional
Specifies the production configuration for the item, including platen size.
Allowed values:
defaultlarge
address
object 
required
Address for order delivery. We will attempt to verify all addresses before accepting orders.
name
string 
required
email
string 
optional
company
string 
optional
phone
string 
optional
street1
string 
required
street2
string 
optional
city
string 
required
state
string 
required
Required with country 'US'
country
string 
required
Must be formatted as ISO 3166-1 two-letter country code.
zip
string 
required
return_address
object 
optional
Address for return order delivery. We will attempt to verify all addresses before accepting orders. if you send data on it will be shown in label tracking
name
string 
required
Full name
email
string 
optional
company
string 
optional
phone
string 
optional
street1
string 
required
street2
string 
optional
city
string 
required
state
string 
required
Required with country 'US'
country
string 
required
Must be formatted as ISO 3166-1 two-letter country code.
zip
string 
required
shipping_method
enum<string> 
required
Additional charges for faster shipping will apply. Please reach out to your sales representative to get the pricing before sending express orders.
Allowed values:
standardpriorityexpressletter_first_class
sample_order
boolean 
optional
Sample Order - For Reconciliation Only. Permission required
reprint_order
boolean 
optional
Reprint Order - For Reconciliation Only. Permission required
is_fba_order
boolean 
optional
Set this field to “true” if it’s an FBA Amazon order, “false” if it’s not. It’s important to note that this field is optional and should only be used for FBA orders. Please reach out to your Sales Representative before placing this.
fba_shipping_label
string 
optional
If the “is_fba_order” field is set to “true”, then this field is required. The value of this field contains the URL where the image file of the shipping label is located. Please ignore this field if it’s not an FBA Amazon Order.
fba_item_label
string 
optional
If the “is_fba_order” field is set to “true”, then this field is required. The value of this field contains the URL where the image file of item label is located. Please ignore this field if it’s not an FBA Amazon Order.
ioss_number
string 
optional
IOSS number: Import One-Stop Shop. The "IOSS number" is assigned to suppliers and electronic interfaces who sell goods to EU buyers. It allows them to handle VAT collection, declaration, and payment to tax authorities, instead of buyers paying VAT during import for goods costing over 22 EUR. For example: IM0560341269. The IOSS number will be displayed on the shipping label.
tax_id
string 
optional
Tax id number. This field becomes mandatory if 'tax_id_type' contains a value.
tax_id_type
enum<string> 
optional
Use this field to specify the type of tax ID. This field becomes mandatory if 'tax_id' contains a value.
Allowed values:
CNPDANDTFDUNEINEOREORIFEDFTZGSTHMRCIOSSLVGMRNPANPIDSDTSSNSTATANTINVATVOECOTHER
insert
array [object {3}] 
optional
The insert array is used to specify additional attachments that should be included with an order. The name available is 'packing_slip'. For 'packing_slip', please provide a valid URL for a PDF or image file in the respective field. If you do not wish to include any attachments with the order, please disregard this array. Please note that each order can have a maximum of one packing slip.
name
enum<string> 
required
Allowed values:
packing_slipgift_message
url
string 
required
Should be PDF URL or image URL
size
enum<string> 
required
Currently we only support size 8.5x11.
Allowed value:
8.5x11
plastic_bag
boolean 
optional
Set this field to 'true' if the order needs to be packed in clear plastic bag packaging, "false" if it's not.
additional_services
array [object {4}] 
optional
Use this field to specify the custom packaging. Please contact Customer support before sending orders with these services
hologram_sticker
string 
optional
mug_packaging
string 
optional
sticker_and_bag
string 
optional
plastic_bag_fee
string 
optional
ship_by_date
string 
optional
Expected date and time the order will be shipped, must be a future date time. This is the reference information for SwiftPOD. Allowed value: datetime with ISO 8601 standard.
Examples:
2025-01-19T20:35:47Z2025-05-30T13:35:03+12:002025-07-08T05:02:47-12:002025-01-19T20:35:47.000Z2025-05-30T13:35:03.123+08:302025-05-30T13:35:03.235-12:30
Example
{
    "order_id": "testord01",
    "test_order": false,
    "order_status": "new_order",
    "line_items": [
        {
            "order_item_id": "item_01",
            "sku": "YOUT1Q0XS",
            "name": "Line Item 1",
            "quantity": 1,
            "print_files": [
                {
                    "key": "front",
                    "url": "https://via.placeholder.com/2400/09f/fff.png"
                },
                {
                    "key": "back",
                    "url": "https://via.placeholder.com/2400/09f/fff.png"
                }
            ],
            "preview_files": [
                {
                    "key": "front",
                    "url": "https://via.placeholder.com/2400/09f/fff.png"
                },
                {
                    "key": "back",
                    "url": "https://via.placeholder.com/2400/09f/fff.png"
                }
            ]
        }
    ],
    "address": {
        "name": "John Smith",
        "email": "johnsmith@demo.com",
        "company": "DEMO",
        "phone": "(330) 638-1331",
        "street1": "4736 Phillips Rice Rd",
        "street2": "",
        "city": "Cortland",
        "state": "OH",
        "country": "US",
        "zip": "44410",
        "force_verified_status": true
    },
    "return_address": {
        "name": "John Smith",
        "email": "johnsmith@demo.com",
        "company": "DEMO",
        "phone": "(330) 638-1331",
        "street1": "4736 Phillips Rice Rd",
        "street2": "",
        "state": "OH",
        "city": "Cortland",
        "country": "US",
        "zip": "44410"
    },
    "shipping_method": "standard",
    "tax_id": "IM0123456888",
    "tax_id_type": "IOSS",
    "insert": [
        {
            "name": "gift_message",
            "url": "https://swiftpod.s3.us-west-1.amazonaws.com/demo/gift-card.jpg",
            "size": "8.5x11"
        }
    ],
    "additional_service": [
        "sticker_and_bag",
        "hologram_sticker"
    ],
    "ship_by_date": "2025-01-19T20:35:47Z"
}

Request samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://api.swiftpod.com/v1/orders' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
    "order_id": "testord01",
    "test_order": false,
    "order_status": "new_order",
    "line_items": [
        {
            "order_item_id": "item_01",
            "sku": "YOUT1Q0XS",
            "name": "Line Item 1",
            "quantity": 1,
            "print_files": [
                {
                    "key": "front",
                    "url": "https://via.placeholder.com/2400/09f/fff.png"
                },
                {
                    "key": "back",
                    "url": "https://via.placeholder.com/2400/09f/fff.png"
                }
            ],
            "preview_files": [
                {
                    "key": "front",
                    "url": "https://via.placeholder.com/2400/09f/fff.png"
                },
                {
                    "key": "back",
                    "url": "https://via.placeholder.com/2400/09f/fff.png"
                }
            ]
        }
    ],
    "address": {
        "name": "John Smith",
        "email": "johnsmith@demo.com",
        "company": "DEMO",
        "phone": "(330) 638-1331",
        "street1": "4736 Phillips Rice Rd",
        "street2": "",
        "city": "Cortland",
        "state": "OH",
        "country": "US",
        "zip": "44410",
        "force_verified_status": true
    },
    "return_address": {
        "name": "John Smith",
        "email": "johnsmith@demo.com",
        "company": "DEMO",
        "phone": "(330) 638-1331",
        "street1": "4736 Phillips Rice Rd",
        "street2": "",
        "state": "OH",
        "city": "Cortland",
        "country": "US",
        "zip": "44410"
    },
    "shipping_method": "standard",
    "tax_id": "IM0123456888",
    "tax_id_type": "IOSS",
    "insert": [
        {
            "name": "gift_message",
            "url": "https://swiftpod.s3.us-west-1.amazonaws.com/demo/gift-card.jpg",
            "size": "8.5x11"
        }
    ],
    "additional_service": [
        "sticker_and_bag",
        "hologram_sticker"
    ],
    "ship_by_date": "2025-01-19T20:35:47Z"
}'

Responses

🟢201Create Order
text/plain
Body
status
boolean 
required
message
string 
required
data
object 
required
id
string 
required
order_id
string 
required
Example
{
    "status": true,
    "message": "Success.",
    "data": {
        "id": "06lz3a11",
        "order_id": "OD-ZA-30"
    }
}
Modified at 2025-07-10 10:54:16
Previous
Orders
Next
Create Multiple Orders
Built with