The wp2print Orders API is an extension of the standard WooCommerce Orders REST API. All standard WooCommerce order endpoints — listing, retrieving, creating, updating, deleting, and batch operations — are available and behave as documented by WooCommerce. wp2print builds on top of this by enriching order responses with print-specific fields on all existing GET endpoints and adding a new endpoint for programmatic order injection.
wp2print hooks into rest_pre_echo_response to append additional fields to every line_items entry in WooCommerce order API responses. This applies to both single-order retrieval (GET /wp-json/wc/v3/orders/<id>) and the order list (GET /wp-json/wc/v3/orders).
The following properties are added to each object in the line_items array:
attributesType: array<string>
Present when: The line item exists in the wp_print_products_order_items table.
An array of the product's print attributes. Each entry is a formatted string:
"Attribute Name: Value" (e.g., "Paper Stock: 100lb Gloss")"; " (newlines in the source are converted to semicolons)Example:
"attributes": [
"Paper Stock: 100lb Gloss",
"Size: 4x6",
"Quantity Option: 500; Double-Sided: Yes"
]
download_filesType: string | array<string>
Present when: Any artwork or design file is associated with the line item.
URLs for downloadable artwork and design files. Sources, in order of precedence:
wp_print_products_order_items.artwork_files (serialized array), resolved to Amazon S3 URLs._artwork_file_url order item meta value._image_link order item meta value (comma-separated list of image URLs from the wp2print designer)._pdf_link order item meta value (comma-separated list of PDF URLs from the wp2print designer).Note: When only a single file URL is present, this field returns a plain
stringrather than an array. When two or more files are present, it returns anarray<string>.
Examples:
"download_files": "https://s3.amazonaws.com/bucket/artwork.pdf"
"download_files": [
"https://s3.amazonaws.com/bucket/artwork.pdf",
"https://example.com/preview.jpg"
]
proofing_statusType: string
Present when: The order has a recognized _approval_status meta value.
The human-readable proofing/approval status for the order, applied uniformly to all line items. Sourced from the _approval_status order meta key and resolved via the print_products_get_approval_statuses() map.
Example:
"proofing_status": "Customer Approved"
production_statusType: string
Present when: The line item has an _item_status meta value.
The human-readable production status for this specific line item. Sourced from the _item_status order item meta key and resolved via print_products_oistatus_get_status_by_slug().
Example:
"production_status": "In Production"
vendor_assignmentType: string
Present when: The line item has an _item_vendor meta value referencing a valid WordPress user.
The vendor or employee assigned to this line item, formatted as "Display Name (email@example.com)". Sourced from the _item_vendor order item meta key, which stores a WordPress user ID.
Example:
"vendor_assignment": "Jane Smith (jane@printshop.com)"
The following shows the line_items array from a real order response (GET /wp-json/wc/v3/orders/1941). Note that download_files is an array when multiple files are present (item 0) and a plain string when only one file exists (item 1).
[
{
"id": 3735,
"name": "Outdoor Banner",
"product_id": 125,
"variation_id": 0,
"quantity": 2,
"tax_class": "",
"subtotal": "311.07",
"subtotal_tax": "27.22",
"total": "311.07",
"total_tax": "27.22",
"taxes": [
{ "id": 1, "total": "27.2188", "subtotal": "27.2188" }
],
"meta_data": [
{ "id": 27636, "key": "_item_status", "value": "awaiting-start" }
],
"sku": "",
"price": 155.536,
"attributes": [
"Width: 35",
"Height: 78",
"Material: Reinforced vinyl",
"Grommets: 4-corners",
"Hemming: Heat-sealed"
],
"download_files": [
"https://wp2printfra.s3.eu-central-1.amazonaws.com/2019-11-26/unknown/RonkonkomaBranch.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=172800&...",
"https://wp2printfra.s3.eu-central-1.amazonaws.com/2019-11-26/unknown/SkatesReturnLabel.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=172800&..."
],
"proofing_status": "Approved for production",
"production_status": "Awaiting Start"
},
{
"id": 3736,
"name": "Rectangular labels",
"product_id": 1764,
"variation_id": 0,
"quantity": 500,
"tax_class": "",
"subtotal": "120.00",
"subtotal_tax": "10.50",
"total": "120.00",
"total_tax": "10.50",
"taxes": [
{ "id": 1, "total": "10.5", "subtotal": "10.5" }
],
"meta_data": [
{ "id": 27647, "key": "_item_status", "value": "awaiting-start" }
],
"sku": "",
"price": 0.24,
"attributes": [
"Size: 2 in x 1 in",
"Color: 4/0 Full-color front only",
"Paper Type: White BOPP",
"Winding: Orientation 2"
],
"download_files": "https://wp2printfra.s3.eu-central-1.amazonaws.com/2019-11-26/unknown/smart-bcard-large-310-310.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=172800&...",
"proofing_status": "Approved for production",
"production_status": "Awaiting Start"
}
]
Creates a WooCommerce order on behalf of an authenticated API user. This endpoint bypasses the WooCommerce storefront flow and is intended for external systems (e.g., storefronts, ERPs) that need to push orders directly into WooCommerce.
POST /wp-json/wc/v1/inject-order/
Note: This endpoint uses the
wc/v1namespace, notwc/v3. It does not use the standard WooCommerce REST API authentication (HTTP Authorization header). Credentials are passed as POST body fields instead.
Authentication uses a standard WooCommerce Consumer Key / Consumer Secret pair, passed as POST fields. These are the same credentials generated under WooCommerce → Settings → Advanced → REST API.
| Field | Type | Description |
|---|---|---|
api_key |
string |
WooCommerce REST API Consumer Key |
api_secret |
string |
WooCommerce REST API Consumer Secret |
The authenticated user's account becomes the order's customer.
Content-Type: application/x-www-form-urlencoded or multipart/form-data
The order data is passed as a JSON string (or decoded associative array) in the data POST field.
| Field | Type | Required | Description |
|---|---|---|---|
billing_address |
object |
Yes | Billing address (see below) |
shipping_address |
object |
Yes | Shipping address (see below) |
products |
array |
Yes | Line items (see below) |
total |
number |
Yes | Order grand total |
payment_method |
string |
No | Payment gateway ID or title (e.g., "bacs", "cheque") |
shipping_method |
string |
No | Shipping method ID or title. Requires shipping_total to take effect. |
shipping_total |
number |
No | Shipping cost |
shipping_weight |
string |
No | Total shipment weight (stored for reference, not used in calculation) |
tax_rate |
number |
No | Tax rate percentage applied to the order |
tax_total |
number |
No | Total tax amount |
billing_address / shipping_address)Both address objects share the same shape. If billing_address.first_name or billing_address.last_name is absent, the value is copied from shipping_address.
| Field | Type | Required | Description |
|---|---|---|---|
first_name |
string |
Yes | |
last_name |
string |
Yes | |
company |
string |
No | |
email |
string |
Yes | Must be a valid email address |
phone |
string |
Yes | |
address_1 |
string |
Yes | Street address line 1 |
address_2 |
string |
No | Street address line 2 |
city |
string |
Yes | |
state |
string |
No | State/province code |
postcode |
string |
Yes | |
country |
string |
Yes | Two-letter ISO 3166-1 country code |
products array)| Field | Type | Required | Description |
|---|---|---|---|
product_id |
number |
Yes | WooCommerce product ID. Must be an existing product. |
quantity |
number |
Yes | Line item quantity |
price |
number |
No | Unit price. Line subtotal is calculated as price × quantity. |
media_url |
string |
No | URL of the artwork file. Stored in wp_print_products_order_items.artwork_files and returned in download_files on subsequent order reads. |
tax |
number |
No | Tax amount for this line item |
weight |
string |
No | Item weight (stored for reference) |
on-hold.calculate_totals() is called internally to compute line totals, but the final order total is always set to the value provided in the total field, overriding WooCommerce's calculation.media_url is provided for a product, a row is inserted into wp_print_products_order_items so the file appears in download_files when the order is later fetched via the standard GET endpoints.payment_method matches a known gateway ID or title, the gateway's title is resolved automatically.shipping_method matches a known shipping method ID or title, the method's ID and title are resolved automatically; otherwise flat_rate is used as a fallback ID.On success, returns HTTP 200 with the following JSON body:
| Field | Type | Description |
|---|---|---|
order_id |
number |
The newly created WooCommerce order ID |
customer |
string |
Display name of the authenticated user |
billing_address |
object |
The billing address as submitted |
shipping_address |
object |
The shipping address as submitted |
products |
array |
The products array as submitted |
total |
number |
The order total as submitted |
Example success response:
{
"order_id": 1042,
"customer": "Acme Corp",
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"email": "john@acmecorp.com",
"phone": "555-1234",
"address_1": "123 Main St",
"city": "Springfield",
"state": "IL",
"postcode": "62701",
"country": "US"
},
"shipping_address": { "..." : "..." },
"products": [
{
"product_id": 101,
"quantity": 500,
"price": 45.00,
"media_url": "https://s3.amazonaws.com/bucket/artwork.pdf"
}
],
"total": 52.50
}
On failure, returns HTTP 401 with a WP REST API error object:
{
"code": "api_authentication_error",
"message": "API key is invalid.",
"data": { "status": 401 }
}
Error codes:
| Code | Cause |
|---|---|
api_authentication_error |
Missing, invalid, or mismatched api_key / api_secret |
api_user_data_error |
Authenticated user ID not found, or data POST field missing/invalid |
api_creating_order_error |
Order creation failed (e.g., required fields missing, invalid product_id) |
POST /wp-json/wc/v1/inject-order/ HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
api_key=ck_xxxxxxxxxxxxxxxxxxxx
&api_secret=cs_xxxxxxxxxxxxxxxxxxxx
&data={
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"company": "Acme Corp",
"email": "john@acmecorp.com",
"phone": "555-1234",
"address_1": "123 Main St",
"address_2": "",
"city": "Springfield",
"state": "IL",
"postcode": "62701",
"country": "US"
},
"shipping_address": {
"first_name": "John",
"last_name": "Doe",
"company": "Acme Corp",
"email": "john@acmecorp.com",
"phone": "555-1234",
"address_1": "123 Main St",
"address_2": "",
"city": "Springfield",
"state": "IL",
"postcode": "62701",
"country": "US"
},
"products": [
{
"product_id": 101,
"quantity": 500,
"price": 45.00,
"media_url": "https://s3.amazonaws.com/bucket/artwork.pdf",
"tax": 3.94
}
],
"payment_method": "bacs",
"shipping_method": "flat_rate",
"shipping_total": 7.50,
"tax_rate": 8.75,
"tax_total": 3.94,
"total": 56.44
}