Podbase API integration guide

Connection

Integration Steps:

1. Create a Podbase account
   • Sign up at Podbase
2. Add a Payment Method
   • Either add a valid payment method or top up your Podbase wallet.
3. Connect to Open API
   
   • Go to Podbase Dashboard > Integrations > Podbase API and click “Connect”.
4. Copy Your API Key

   • Click the “Copy” button to save your API key.

   • You will not see this key again after leaving the page.

5. 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

1. External order id.
2. Buyer contact information.
3. Delivery address information.
4. Shipping type id.
5. Items.

Each order must include the following 5 parts:

1. External Order ID

   • Must be unique to your store.

   • Used for identifying the order in case of issues.

2. Buyer Contact Information

   • Required: Full name, phone number

   • Optional: Email address (recommended)

3. Delivery Address

   Field	Required
   Line 1	Required
   Line 2	Optional
   City	Required
   Postal Code	Required
   Country	Required
   Region	Optional

4. 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.

5. 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.

---

Testing

Before going live, we recommend testing your order flow. Since testing is performed in the production environment, one of the steps involves submitting and paying for an order. To avoid being charged for test orders, please follow the steps below:

• Go to Podbase > Store Settings > Orders and set your Order Approval to Manual approval.
  
• While set to Manual, your orders will be created in Podbase with Unapproved status. This allows you to freely cancel or approve them without incurring any charges.

• After your integration is fully tested and stable, you can switch the Order Approval setting back to Automatic for a smooth and hands-free order processing experience.