Skip to content
  • There are no suggestions because the search field is empty.

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:

  1. Create a Podbase account
  2. Add a Payment Method
    • Either add a valid payment method or top up your Podbase wallet.
  3. Connect to Open API
  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:


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.