Skip to main content

What can the Podbase API be used for?

Updated

Overview

The Podbase API exposes four primary endpoints for managing print-on-demand orders and products:

  • POST /orders - Submit new orders for fulfillment

  • GET /orders - Retrieve multiple orders with pagination

  • GET /orders/{orderId} - Retrieve details for a specific order

  • GET /catalog - Retrieve the current product catalog

1. POST /orders - Submit New Orders

Purpose
Create and submit new print-on-demand orders for fulfillment.

Key capabilities

  • Programmatically create new orders

  • Automatically fulfill orders from your store or platform

  • Submit bulk orders

  • Process custom products with user-uploaded designs

Example Request

Endpoint

POST https://open-api.podbase.com/orders
 


Headers 

x-api-key: your_api_key_here
Content-Type: application/json
 


Request Body 

{
"externalOrderId": "ORDER-12345",
"buyer": {
"fullName": "John Smith",
"phone": "+1234567890",
"email": "john@example.com"
},
"deliveryAddress": {
"line1": "123 Main Street",
"line2": "Apt 4B",
"city": "New York",
"postalCode": "10001",
"country": "US",
"region": "NY"
},
"shippingTypeId": "PBS-F7-7ZH-223S",
"items": [
{
"productId": "PBP-123-ABC",
"variantId": "PBV-123-ADC",
"quantity": 2,
"printFile": "https://example.com/designs/custom-design.png",
"externalProductId": "MY-PRODUCT-001",
"title": "Custom iPhone Case",
"price": 29.99
}
]
}

Example Response - Success

Status: 201 Created 

{
"orderId": "PB-ORD-987654",
"externalOrderId": "ORDER-12345",
"status": "PENDING",
"createdAt": "2026-02-01T10:30:00Z",
"items": [
{
"itemId": "ITEM-001",
"productId": "PROD-ABC-123",
"variantId": "VAR-XYZ-789",
"quantity": 2,
"status": "PENDING"
}
]
}

Example Response - Error

Status: 400 Bad Request

{
"error": "Invalid shipping type ID",
"message": "The provided shippingTypeId is not valid",
"field": "shippingTypeId"
}

Shipping Type IDs

  • Economy Delivery: PBS-F7-7ZH-223S

  • Express Delivery: PBS-3K-HSP-223D

2. GET /orders - Retrieve Multiple Orders

Purpose
Retrieve a paginated list of orders with optional filtering.

Key capabilities

  • View all orders

  • Track order statuses in bulk

  • Build order management dashboards

  • Generate order volume reports

  • Sync orders with your internal database

  • Monitor fulfillment progress

Example Request

GET https://open-api.podbase.com/orders?page=1&limit=10&status=FULFILLED
 


Headers 

x-api-key: your_api_key_here
 


Query Parameters

  • page — Page number (default: 1)

  • limit — Items per page (default: 10, max: 100)

  • status — Filter by status (PENDING, PROCESSING, FULFILLED, CANCELLED)

  • startDate — Filter orders from this date (ISO 8601)

  • endDate — Filter orders until this date (ISO 8601)

Example Response

Status: 200 OK 

{
"orders": [
{
"orderId": "PBO-123-123-123",
"externalOrderId": "ORDER-12345",
"status": "FULFILLED",
"createdAt": "2021-01-01T10:30:00Z",
"fulfilledAt": "2021-01-03T14:22:00Z",
"trackingNumber": "1Z999AA10123456784",
"carrier": "DHL",
"buyer": {
"fullName": "John Smith",
"email": "john@example.com"
},
"items": [
{
"itemId": "ITEM-001",
"productId": "PBP-ABC-123",
"variantId": "PBV-XYZ-789",
"quantity": 2,
"status": "FULFILLED"
}
]
},
{
"orderId": "PBO-123-123-ABC",
"externalOrderId": "ORDER-12346",
"status": "FULFILLED",
"createdAt": "2021-01-20T11:15:00Z",
"fulfilledAt": "2021-01-25T16:45:00Z",
"trackingNumber": "1Z999AA10123456785",
"carrier": "DHL",
"buyer": {
"fullName": "Jane Doe",
"email": "jane@example.com"
},
"items": [
{
"itemId": "ITEM-002",
"productId": "PBP-124-ABC",
"variantId": "PBV-123-125",
"quantity": 1,
"status": "FULFILLED"
}
]
}
],
"pagination": {
"currentPage": 1,
"totalPages": 5,
"totalOrders": 47,
"limit": 10
}
}

Common Use Cases

  • Display pending orders in an admin dashboard

  • Retrieve last month’s fulfilled orders for reporting

  • Monitor processing orders to estimate fulfillment time

  • Analyze cancelled orders and rejection reasons

3. GET /orders/{orderId} - Retrieve Order Details

Purpose
Retrieve full details for a single order.

Key capabilities

  • Check order status

  • Retrieve tracking information

  • Verify order details

  • Support customer inquiries

  • Communicate order progress

  • Debug fulfillment issues

Example Request

GET https://open-api.podbase.com/orders/PB-ORD-987654
 


Headers

x-api-key: your_api_key_here
 


Example Response - Fulfilled Order

Status: 200 OK

{
"orderId": "PBO-123-123-132",
"externalOrderId": "ORDER-12345",
"status": "FULFILLED",
"createdAt": "2026-01-28T10:30:00Z",
"approvedAt": "2026-01-28T10:31:00Z",
"processingStartedAt": "2026-01-28T14:00:00Z",
"fulfilledAt": "2026-01-29T14:22:00Z",
"trackingNumber": "1Z999AA10123456784",
"carrier": "DHL",
"estimatedDelivery": "2026-02-03T23:59:59Z",
"buyer": {
"fullName": "John Smith",
"phone": "+1234567890",
"email": "john@example.com"
},
"deliveryAddress": {
"line1": "123 Main Street",
"line2": "Apt 4B",
"city": "New York",
"postalCode": "10001",
"country": "US",
"region": "NY"
},
"shippingTypeId": "PBS-F7-7ZH-223S",
"shippingType": "Economy Delivery",
"items": [
{
"itemId": "ITEM-001",
"productId": "PBP-123-ABC",
"productName": "Tough Case",
"variantId": "PBV-123-123",
"variantName": "iPhone 15 Pro ",
"quantity": 2,
"printFile": "https://example.com/designs/custom-design.png",
"externalProductId": "MY-PRODUCT-001",
"title": "Custom iPhone Case",
"price": 29.99,
"status": "FULFILLED"
}
],
"totalCost": 45.98
}

Order Status Values

  • PENDING - Submitted, awaiting approval

  • APPROVED - Approved, awaiting production

  • PROCESSING - In production

  • FULFILLED - Shipped with tracking

  • CANCELLED - Order cancelled

4. GET /catalog - Retrieve Product Catalog

Purpose
Retrieve available products, variants, pricing, and print requirements.

Key capabilities

  • Display products in your store

  • Build product selection flows

  • Retrieve pricing data

  • Validate product and variant IDs

  • Sync product data automatically

  • Display design requirements

Example Request

 
GET https://open-api.podbase.com/catalog
 

Headers

 
x-api-key: your_api_key_here
 

Example Response

{
  "lastUpdated": "2021-01-01T00:00:00Z",
  "products": [
    {
      "productId": "PBP-123-123",
      "name": "iPhone Pro Tough Case",
      "description": "Super awesome case",
      "category": "Phone Cases",
      "basePrice": 59.99,
      "printArea": {
        "width": 3200,
        "height": 3200,
        "unit": "pixels",
        "dpi": 300
      },
      "variants": [
        {
          "variantId": "PBV-XYZ-789",
          "name": "iPhone15",
          "sku": "IP15",
          "available": true
        },
        {
          "variantId": "PBV-XYZ-790",
          "name": "iPhone15 Pro ",
          "sku": "IP15P",
          "available": true
        },
        {
          "variantId": "PBV-XYZ-791",
          "name": "iPhone 15 Pro Max ",
          "sku": "IP15PM",
          "available": true
        }
      ],
      "images": [
        {
          "type": "mockup",
          "url": "https://podbase.com/mockups/iphone-15-pro-black.png"
        }
      ]
    },

 

Practical Workflow Example

A complete order lifecycle using all endpoints:

1. Retrieve Products

GET /catalog
 

  • Display products

  • Store productId and variantId

2. Submit Order

POST /orders
 

  • Submit order and design

  • Store returned orderId

3. Track Order

GET /orders/{orderId}
 

  • Poll for status updates

  • Retrieve tracking when fulfilled

4. Manage Orders in Bulk

GET /orders?status=PROCESSING
 

  • Display production orders

  • Generate reports

Authentication

All requests require an API key:

 
x-api-key: your_api_key_here


API Key Location

Dashboard → Integrations → Podbase API

Related articles

Comments

0 comments

Article is closed for comments.