Podbase API integration guide
Connection
The complete Open API Specification, including all payloads and data types, is available here: Open API Specification
Contact the developer
Integration Steps:
- Create a Podbase account
- Sign up at Podbase
- Add a Payment Method
- Either add a valid payment method or top up your Podbase wallet.
- Connect to Open API
- Go to Podbase Dashboard > Integrations > Podbase API and click “Connect”.
- Copy Your API Key
-
Click the “Copy” button to save your API key.
-
You will not see this key again after leaving the page.
-
- Lost Your API Key?
- Click “Generate a new key” to replace it.
- Your old key will become invalid immediately.
Important Note
- Only one integration per Podbase User Store is allowed.
- If another integration is already connected, you must either:
- Create a new user store, or
- Disconnect the existing integration before connecting the Open API.
Authentication
All Podbase Open API endpoints require authentication.
Request Header
Add your API Key’s raw value to the header:
x-api-key: YOUR_API_KEY
Order Import
Use the endpoint below to import orders into Podbase:
POST /orders
Detailed schema and parameters are available in the Open API Specification
Required Data Components
- External order id.
- Buyer contact information.
- Delivery address information.
- Shipping type id.
- Items.
Each order must include the following 5 parts:
-
External Order ID
-
Must be unique to your store.
-
Used for identifying the order in case of issues.
-
-
Buyer Contact Information
-
Required: Full name, phone number
-
Optional: Email address (recommended)
-
-
Delivery Address
Field Required Line 1 Required Line 2 Optional City Required Postal Code Required Country Required Region Optional -
Shipping Type ID
ID Shipping Type PBS-F7-7ZH-223S
Economy Delivery PBS-3K-HSP-223D
Express Delivery -
You must provide a valid shipping type ID.
-
Invalid IDs cause automatic cancellation — the order must then be re-imported.
-
-
Items
Each item includes 6 properties:Property Required Description productId
Required Retrieved via GET /catalog
variantId
Required Retrieved via GET /catalog
quantity
Required Number of physical units printFile
Required Public URL (JPG, JPEG, PNG, TIF, TIFF only) externalProductId
Required ID provided by the API user — a.k.a. user product ID. It represents a merged value derived from fields like ProductId, VariantId, and PrintFile. title
Optional Product title is the name of the user product created in Podbase platform. price
Optional Product price is the price of the user product created in Podbase platform. This price is used as a reference to calculate potential profit on the Podbase platform once user create orders directly in the platform. Once the user product is created, this price is also pushed to other integrations. (It is not the price at which Podbase sells products to the API user.) ⚠️ Print File Requirements:
-
Must not require authentication
-
Must comply with Podbase’s print file guidelines:
How to prepare designs for Podbase? (quick review) -
Non-compliant or incorrect designs are not refundable.
-
Order Retrieval
You can track and retrieve order information as it progresses through the fulfillment process.
- Get a single order:
GET /orders/{orderId}
- Get multiple (paginated) orders:
GET /orders
Once an order is processed, it will reach the status FULFILLED
and include a tracking number.
Catalog Retrieval
To successfully import orders, you must use Podbase internal product IDs and variant IDs.
Retrieve the latest catalog data using:
GET /catalog
Important Note
- Regularly refresh your catalog data
- Podbase catalog updates frequently — new products are added, variants renamed or removed
- Orders referencing deprecated products or variants will be rejected.