API Reference Documentation

Integrate your e-commerce storefronts directly with Albovo's automated print-on-demand fulfillment pipeline.

Base API URL

api.albovo.com/api/v2

API Key Authentication

X-API-Key: albovo_live_...

GET/api/v2/ordersAPI Key

Get Orders

Retrieves a paginated list of orders belonging to the authenticated client, with aggregated status counters in meta.status.

Request Headers

Field / Parameter	Requirement	Description
X-API-Key	Required	Persistent API Key generated from Dashboard → API Keys (or 'Authorization: Bearer <API_KEY>')
X-Timezone	Optional	Optional header to convert created_at and updated_at timestamps to your local timezone (e.g. 'Asia/Ho_Chi_Minh', 'America/New_York')

Query Parameters

Field / Parameter	Type	Requirement	Description
page	integer	Optional	Page number for pagination (starts at 1) (default: 1)
per_page	integer	Optional	Number of orders returned per page (default: 10, max: 100) (default: 10)
status	string	Optional	Filter by status: 'Awaiting Payment', 'In Production', 'Shipped', 'In Transit', 'Delivered', 'Cancelled', 'On Hold' (default: null)
search	string	Optional	Search keyword matching order ID, customer name, email, or tracking number (default: null)
from_date	string (YYYY-MM-DD)	Optional	Filter orders created on or after this calendar date (inclusive, starts 00:00:00 in request timezone). (default: null)
to_date	string (YYYY-MM-DD)	Optional	Filter orders created on or before this calendar date (inclusive, ends 23:59:59 in request timezone). (default: null)

cURL Example

curl -X GET "https://api.albovo.com/api/v2/orders?from_date=2026-08-01&to_date=2026-08-25&status=Shipped&page=1&per_page=10" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Timezone: Asia/Ho_Chi_Minh"

Response Statuses

Paginated list of orders with meta status breakdown counters.

{
  "success": true,
  "message": "Orders retrieved successfully",
  "data": {
    "meta": {
      "page": 1,
      "per_page": 10,
      "total": 2,
      "total_pages": 1,
      "status": {
        "Awaiting Payment": 1,
        "In Production": 1,
        "Shipped": 0,
        "In Transit": 0,
        "Delivered": 0,
        "Cancelled": 0,
        "On Hold": 0
      }
    },
    "orders": [
      {
        "order_id": "ORD-20260811-A1B2C",
        "order_ref": "ORD-CLIENT-1001",
        "status": "Awaiting Payment",
        "print_technique": "dtg",
        "address_to": {
          "name": "John Doe",
          "address1": "123 Main Street",
          "address2": "Suite 4B",
          "city": "San Francisco",
          "region": "CA",
          "zip": "94105",
          "country": "US",
          "email": "john.doe@example.com",
          "phone": "+1234567890"
        },
        "shipment": {
          "tracking_number": "TRK123456789",
          "label_url": "https://example.com/labels/label_123.pdf"
        },
        "total_items_price": 24.5,
        "shipping_price": 0.5,
        "total_price": 25,
        "created_at": "2026-08-11T16:25:00+07:00",
        "updated_at": "2026-08-11T16:25:00+07:00",
        "items": [
          {
            "id": 501,
            "sku": "G5000-BLACK-M",
            "quantity": 2,
            "item_price": 12.25,
            "item_price_total": 24.5,
            "preview_files": {
              "front": "https://example.com/mockups/front.png",
              "back": ""
            },
            "print_files": {
              "front": "https://example.com/designs/front.png",
              "back": ""
            }
          }
        ]
      }
    ]
  }
}

POST/api/v2/ordersAPI Key

Create Order

Submits a new print order to the portal in 'Awaiting Payment' status. Supports Platform Delivery (with address) or Prepaid Carrier Label (with tracking number & label URL).

Request Headers

Field / Parameter	Requirement	Description
X-API-Key	Required	Persistent API Key generated from Dashboard → API Keys (or 'Authorization: Bearer <API_KEY>')
Content-Type	Required	JSON payload body

Request Payload

Field / Parameter	Type	Requirement	Description
order_ref	string	Required	Client's unique external order reference ID (e.g. ORD-CLIENT-1001).
print_technique	string ('dtg' \| 'dtf')	Optional	Print technique: 'dtg' (Direct-to-Garment) or 'dtf' (Direct-to-Film). Defaults to 'dtg'.
address_to	object	Conditional	Delivery address object. Required if no prepaid shipment label is provided.
address_to.name	string (2-100 chars)	Required	Recipient full name.
address_to.raw_address	string (single-line address)	Conditional	Full single-line US shipping address string (e.g. '123 Main St Suite 4B, San Francisco, CA 94105'). Mutually exclusive with address1/city/region/zip.
address_to.email	string	Optional	Recipient contact email.
address_to.phone	string	Optional	Recipient contact phone number.
address_to.address1	string (max 100 chars)	Conditional	Primary street address.
address_to.address2	string (max 100 chars)	Optional	Apartment, suite, unit, or building (optional).
address_to.city	string (2-50 chars)	Conditional	City / District.
address_to.region	string (USPS state code / name)	Conditional	US state or territory: all 62 valid USPS codes (e.g. CA, NY, PR, TX) or full state name (auto-mapped).
address_to.zip	string (5 or 9-digit ZIP)	Conditional	US ZIP code: 5 digits ('90210') or 9 digits with hyphen ('90210-1234').
address_to.country	string (default 'US')	Optional	Destination country. Defaults to 'US'. Domestic US shipping only ('US', 'USA', 'United States').
address_to.verify	boolean (default true)	Optional	Optional boolean (default true). Determines whether carrier address verification is performed via 2-layer engine (internal cache + EasyPost) when pushed to factory. Set false to bypass verification for unindexed addresses. Note: If false, Albovo bears no responsibility for missing, undelivered, or returned shipments.
shipment	object	Conditional	Prepaid carrier shipment details. Required if no recipient delivery address is provided.
shipment.tracking_number	string	Required	Carrier tracking number.
shipment.label_url	string (url)	Required	Direct accessible URL to shipping label file (PDF or PNG).
items	array[object]	Required	Array of order items (minimum 1 item required).
items[].sku	string	Required	Catalog SKU formatted as SHIRTCODE-COLOR-SIZE (e.g. G5000-BLACK-M).
items[].quantity	integer	Required	Quantity of garments for this variant (minimum 1).
items[].preview_files	object	Conditional	Mockup preview image URLs (front, back, sleeve_left, sleeve_right). Must bi-directionally match print files.
items[].preview_files.front	string (url)	Optional	Mockup preview URL for front placement.
items[].preview_files.back	string (url)	Optional	Mockup preview URL for back placement.
items[].preview_files.sleeve_left	string (url)	Optional	Mockup preview URL for left sleeve placement.
items[].preview_files.sleeve_right	string (url)	Optional	Mockup preview URL for right sleeve placement.
items[].print_files	object	Required	High-resolution print design URLs (front, back, sleeve_left, sleeve_right). At least one main print (front/back) required.
items[].print_files.front	string (url)	Optional	High-resolution print artwork URL (300 DPI PNG) for front placement.
items[].print_files.back	string (url)	Optional	High-resolution print artwork URL (300 DPI PNG) for back placement.
items[].print_files.sleeve_left	string (url)	Optional	High-resolution print artwork URL (300 DPI PNG) for left sleeve placement.
items[].print_files.sleeve_right	string (url)	Optional	High-resolution print artwork URL (300 DPI PNG) for right sleeve placement.

cURL Example

curl -X POST "https://api.albovo.com/api/v2/orders" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_ref": "ORD-CLIENT-1001",
    "print_technique": "dtg",
    "address_to": {
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "phone": "+1 (415) 555-1234",
      "address1": "PO Box 255 182 Smokestack Hill Rd",
      "city": "San Francisco",
      "region": "California",
      "zip": "94105-1234",
      "country": "US"
    },
    "shipment": {
      "tracking_number": "TRK123456789",
      "label_url": "https://example.com/labels/label_123.pdf"
    },
    "items": [
      {
        "sku": "G5000-BLACK-M",
        "quantity": 2,
        "preview_files": {
          "front": "https://example.com/mockups/front.png"
        },
        "print_files": {
          "front": "https://example.com/designs/front.png"
        }
      }
    ]
  }'

Response Statuses

Order created successfully in 'Awaiting Payment' status.

{
  "success": true,
  "message": "Order created successfully",
  "data": {
    "order_id": "ORD-20260811-A1B2C",
    "order_ref": "ORD-CLIENT-1001",
    "status": "Awaiting Payment",
    "print_technique": "dtg",
    "total_items_price": 24.5,
    "shipping_price": 0.5,
    "total_price": 25,
    "created_at": "2026-08-11T16:25:00+00:00",
    "items": [
      {
        "id": 501,
        "sku": "G5000-BLACK-M",
        "quantity": 2,
        "item_price": 12.25,
        "item_price_total": 24.5
      }
    ]
  }
}

POST/api/v2/orders/rateAPI Key

Estimate Order Rate

Calculates live price breakdown, item unit costs, and shipping fees without creating a persistent database order record.

Request Headers

Field / Parameter	Requirement	Description
X-API-Key	Required	Persistent API Key generated from Dashboard → API Keys (or 'Authorization: Bearer <API_KEY>')
Content-Type	Required	JSON payload body

Request Payload

Field / Parameter	Type	Requirement	Description
order_ref	string	Required	Client's unique external order reference ID (e.g. ORD-CLIENT-1001).
print_technique	string ('dtg' \| 'dtf')	Optional	Print technique: 'dtg' (Direct-to-Garment) or 'dtf' (Direct-to-Film). Defaults to 'dtg'.
address_to	object	Conditional	Delivery address object. Required if no prepaid shipment label is provided.
address_to.name	string	Conditional	Recipient full name.
address_to.raw_address	string (single-line address)	Conditional	Full single-line US shipping address string (e.g. '123 Main St Suite 4B, San Francisco, CA 94105'). Mutually exclusive with address1/city/region/zip.
address_to.address1	string	Conditional	Primary street address.
address_to.address2	string	Optional	Apartment, suite, unit, or building (optional).
address_to.city	string	Conditional	City / District.
address_to.region	string	Conditional	US state or territory: all 62 valid USPS codes (e.g. CA, NY, PR, TX) or full state name (auto-mapped).
address_to.zip	string	Conditional	US ZIP code: 5 digits ('90210') or 9 digits with hyphen ('90210-1234').
address_to.country	string	Optional	Destination country. Defaults to 'US'. Domestic US shipping only ('US', 'USA', 'United States').
address_to.verify	boolean (default true)	Optional	Optional boolean (default true). Determines whether carrier address verification is performed via 2-layer engine (internal cache + EasyPost) when pushed to factory. Set false to bypass verification for unindexed addresses. Note: If false, Albovo bears no responsibility for missing, undelivered, or returned shipments.
address_to.email	string	Optional	Recipient contact email.
address_to.phone	string	Optional	Recipient contact phone number.
shipment	object	Conditional	Prepaid carrier shipment details. Required if no recipient delivery address is provided.
shipment.tracking_number	string	Conditional	Carrier tracking number.
shipment.label_url	string (url)	Conditional	Direct accessible URL to shipping label file (PDF or PNG).
items	array[object]	Required	Array of order items (minimum 1 item required).
items[].sku	string	Required	Catalog SKU formatted as SHIRTCODE-COLOR-SIZE (e.g. G5000-BLACK-M).
items[].quantity	integer	Required	Quantity of garments for this variant (minimum 1).
items[].preview_files	object	Conditional	Mockup preview image URLs (front, back, sleeve_left, sleeve_right). Must bi-directionally match print files.
items[].print_files	object	Required	High-resolution print design URLs (front, back, sleeve_left, sleeve_right). At least one main print (front/back) required.

cURL Example

curl -X POST "https://api.albovo.com/api/v2/orders/rate" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_ref": "ORD-ESTIMATE-1001",
    "print_technique": "dtg",
    "address_to": {
      "name": "Jane Doe",
      "address1": "123 Main Street",
      "address2": "Suite 4B",
      "city": "San Francisco",
      "region": "CA",
      "zip": "94105",
      "country": "US"
    },
    "items": [
      {
        "sku": "G5000-BLACK-M",
        "quantity": 2,
        "print_files": { "front": "https://example.com/designs/front.png" },
        "preview_files": { "front": "https://example.com/mockups/front.png" }
      }
    ]
  }'

Response Statuses

Order rate and per-item pricing estimated successfully (Standard OrderDetailResponseData schema).

{
  "success": true,
  "message": "Order rate calculated successfully",
  "data": {
    "order_id": null,
    "order_ref": "ORD-ESTIMATE-1001",
    "status": "Estimate",
    "address_to": {
      "name": "Jane Doe",
      "address1": "123 Main Street",
      "address2": "Suite 4B",
      "city": "San Francisco",
      "region": "CA",
      "zip": "94105",
      "country": "US",
      "phone": "+1 (415) 555-1234",
      "email": "jane.doe@example.com"
    },
    "shipment": {
      "tracking_number": "",
      "label_url": ""
    },
    "print_technique": "dtg",
    "total_items_price": 31.5,
    "shipping_price": 7.5,
    "total_price": 39,
    "created_at": null,
    "updated_at": null,
    "items": [
      {
        "id": null,
        "sku": "G5000-BLACK-M",
        "quantity": 2,
        "item_price": 11,
        "item_price_total": 22,
        "preview_files": {
          "front": "https://example.com/mockups/front_g5000.png",
          "back": "https://example.com/mockups/back_g5000.png",
          "sleeve_left": null,
          "sleeve_right": null
        },
        "print_files": {
          "front": "https://example.com/designs/front_g5000.png",
          "back": "https://example.com/designs/back_g5000.png",
          "sleeve_left": null,
          "sleeve_right": null
        }
      },
      {
        "id": null,
        "sku": "BC3001-WHITE-L",
        "quantity": 1,
        "item_price": 9.5,
        "item_price_total": 9.5,
        "preview_files": {
          "front": "https://example.com/mockups/front_bc3001.png",
          "back": null,
          "sleeve_left": null,
          "sleeve_right": null
        },
        "print_files": {
          "front": "https://example.com/designs/front_bc3001.png",
          "back": null,
          "sleeve_left": null,
          "sleeve_right": null
        }
      }
    ]
  }
}

PUT/api/v2/orders/{order_id}API Key

Edit Order

Updates address details, shipping label, print technique, or artwork items for an order in 'Awaiting Payment' status. Orders already 'In Production' cannot be modified.

Request Headers

Field / Parameter	Requirement	Description
X-API-Key	Required	Persistent API Key generated from Dashboard → API Keys (or 'Authorization: Bearer <API_KEY>')
Content-Type	Required	JSON payload body

Request Payload

Field / Parameter	Type	Requirement	Description
order_id (path)	string	Required	Unique order ID (e.g. ORD-20260811-A1B2C) or client external order reference.
address_to	object	Optional	Updated delivery address object
address_to.name	string	Optional	Recipient full name.
address_to.raw_address	string	Optional	Full single-line US shipping address string (e.g. '123 Main St Suite 4B, San Francisco, CA 94105'). Mutually exclusive with address1/city/region/zip.
address_to.address1	string	Optional	Primary street address.
address_to.city	string	Optional	City / District.
address_to.region	string	Optional	US state or territory: all 62 valid USPS codes (e.g. CA, NY, PR, TX) or full state name (auto-mapped).
address_to.zip	string	Optional	US ZIP code: 5 digits ('90210') or 9 digits with hyphen ('90210-1234').
address_to.country	string	Optional	Destination country. Defaults to 'US'. Domestic US shipping only ('US', 'USA', 'United States').
address_to.verify	boolean (default true)	Optional	Optional boolean (default true). Determines whether carrier address verification is performed via 2-layer engine (internal cache + EasyPost) when pushed to factory. Set false to bypass verification for unindexed addresses. Note: If false, Albovo bears no responsibility for missing, undelivered, or returned shipments.
shipment	object	Optional	Updated tracking_number and label_url
print_technique	string ('dtg' \| 'dtf')	Optional	Updated print method
items	array[object]	Optional	Updated items array replacing all existing items in the order
items[].sku	string	Required	Catalog SKU formatted as SHIRTCODE-COLOR-SIZE (e.g. G5000-BLACK-M).
items[].quantity	integer	Required	Quantity of garments for this variant (minimum 1).
items[].preview_files	object	Conditional	Mockup preview image URLs (front, back, sleeve_left, sleeve_right). Must bi-directionally match print files.
items[].preview_files.front	string (url)	Optional	Mockup preview URL for front placement.
items[].preview_files.back	string (url)	Optional	Mockup preview URL for back placement.
items[].preview_files.sleeve_left	string (url)	Optional	Mockup preview URL for left sleeve placement.
items[].preview_files.sleeve_right	string (url)	Optional	Mockup preview URL for right sleeve placement.
items[].print_files	object	Required	High-resolution print design URLs (front, back, sleeve_left, sleeve_right). At least one main print (front/back) required.
items[].print_files.front	string (url)	Optional	High-resolution print artwork URL (300 DPI PNG) for front placement.
items[].print_files.back	string (url)	Optional	High-resolution print artwork URL (300 DPI PNG) for back placement.
items[].print_files.sleeve_left	string (url)	Optional	High-resolution print artwork URL (300 DPI PNG) for left sleeve placement.
items[].print_files.sleeve_right	string (url)	Optional	High-resolution print artwork URL (300 DPI PNG) for right sleeve placement.

cURL Example

curl -X PUT "https://api.albovo.com/api/v2/orders/ORD-20260811-A1B2C" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address_to": {
      "name": "Jane Doe Updated",
      "address1": "456 Market Street",
      "city": "San Francisco",
      "region": "CA",
      "zip": "94103",
      "country": "US"
    },
    "shipment": {
      "tracking_number": "TRK987654321",
      "label_url": "https://example.com/labels/label_updated.pdf"
    },
    "items": [
      {
        "sku": "G5000-BLACK-L",
        "quantity": 3,
        "preview_files": {
          "front": "https://example.com/mockups/front_v2.png"
        },
        "print_files": {
          "front": "https://example.com/designs/front_v2.png"
        }
      }
    ]
  }'

Response Statuses

Order modified successfully.

{
  "success": true,
  "message": "Order updated successfully",
  "data": {
    "order_id": "ORD-20260811-A1B2C",
    "status": "Awaiting Payment",
    "updated_at": "2026-08-13T09:41:00+07:00",
    "total_price": 25
  }
}

POST/api/v2/orders/push-to-factoryAPI Key

Push Orders to Factory

Transitions orders from 'Awaiting Payment' to 'In Production'. Automatically validates wallet coin balance and deducts order costs per item. Unfunded orders are skipped and returned in failed_orders.

Request Headers

Field / Parameter	Requirement	Description
X-API-Key	Required	Persistent API Key generated from Dashboard → API Keys (or 'Authorization: Bearer <API_KEY>')
Content-Type	Required	JSON payload body

Request Payload

Field / Parameter	Type	Requirement	Description
internal_ids	array[string]	Required	Array of order IDs or client external refs to process (e.g. ['ORD-20260811-A1B2C']).

cURL Example

curl -X POST "https://api.albovo.com/api/v2/orders/push-to-factory" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "internal_ids": [
      "ORD-20260811-A1B2C",
      "ORD-20260811-D3E4F"
    ]
  }'

Response Statuses

Batch push summary with wallet balance deduction per order.

{
  "success": true,
  "message": "Push to factory processing completed",
  "data": {
    "meta": {
      "total_processed": 2,
      "success_count": 1,
      "failed_count": 1
    },
    "success_orders": [
      {
        "internal_id": "ORD-20260811-A1B2C"
      }
    ],
    "failed_orders": [
      {
        "internal_id": "ORD-20260811-D3E4F",
        "reason": "Insufficient balance (5.00 coins available, 45.00 required)",
        "error_code": "insufficient_balance",
        "order_total": 45
      }
    ]
  }
}

GET/api/v2/wallet/balanceAPI Key

Get Wallet Balance

Retrieves the current available credit/coin balance (in USD) for the authenticated client account.

Request Headers

Field / Parameter	Requirement	Description
X-API-Key	Required	Persistent API Key generated from Dashboard → API Keys (or 'Authorization: Bearer <API_KEY>')

cURL Example

curl -X GET "https://api.albovo.com/api/v2/wallet/balance" \
  -H "X-API-Key: YOUR_API_KEY"

Response Statuses

Current wallet credit balance retrieved.

{
  "success": true,
  "message": "Wallet balance retrieved successfully",
  "data": {
    "balance": 1500.5
  }
}

Need Custom API Integration or Webhook Callbacks?

Our engineering team supports automated order webhooks and custom platform synchronization.