Overview

This document describes the minimal set of API endpoints needed for Customily to interact with a Print on Demand (POD) provider. The JSON examples are for demonstration purposes as we can adapt to your JSON response structure.

1. Get Products - Retrieve a list of products.
2. Get Product Details - Retrieve details for a specific product.
3. Create Order - Place an order for a selected product and variants
4. Package Shipped Webhook - Receive notifications when a package has been shipped.

Get Products

Purpose:
The Get Products endpoint allows our application to retrieve a list of all available products from the POD provider. This is useful for displaying a catalog or product selection menu.

HTTP Method:
GET

URL:
https://api.podprovider.com/v1/products

Query Parameters:

• limit (integer, optional): The maximum number of products to retrieve in a single request (default: 20).
• offset (integer, optional): The number of products to skip before starting to retrieve results (useful for pagination).

Response Format:
The response will be in JSON format and include a list of basic product details for each product.

Expected JSON Response Structure

• products (array): An array of product objects, each containing basic information about a product. Each product object includes:
  • productId (string): The unique identifier for the product in the POD provider's system.
  • productName (string): The name of the product, as registered with the POD provider.
  • description (string): A brief description of the product.
  • price (number): The base price of the product, in USD.
  • thumbnailURL (string): A URL pointing to a thumbnail image of the product.

Get Product Details

Purpose:
The Get Product Details endpoint allows our application to pull comprehensive details for a specific product, including variant options, pricing, and fulfillment time.

HTTP Method:
GET

URL:
https://api.podprovider.com/v1/products/{productId}

Path Parameter:

• productId (string): The unique identifier for the product to retrieve details for.

Response Format:
The response will be in JSON format and include detailed information about the selected product.

Expected JSON Response Structure

Field Descriptions

• PODProductId (string): The unique identifier for the product in the POD provider's system.

• productName (string): The name of the product.

• description (string): A brief description of the product.

• variants (array): An array of objects representing different attribute types and available options. Each variant group contains:

  • id (string): A unique identifier for the variant group.
  • attribute (string): The type of attribute (e.g., color, size, material).
  • options (array): An array of option objects for this attribute. Each option includes:
    • value (string): The specific value for this option (e.g., Red, Blue, S, Cotton).
    • hex (string, optional): The hexadecimal color code for color options (if attribute is color).
    • imageURL (string): A URL for an image representing the option.
    • printFiles (array): An array of objects representing each print file associated with this option. Each print file includes:
      • id (string): The unique identifier for the print file.
      • name (string): A descriptive name for the print file (e.g., "front", "back").
      • url (string): The URL pointing to the print file.

• price (number): The base price of the product, in USD.

• averageFulfillmentTime (number): The average time, in business days, that the POD provider needs to fulfill an order for this product.

Create Order

Purpose:
The Create Order endpoint allows our application to submit an order for a specified product variant. This endpoint will include order details, shipping options, recipient information, and product specifications.

HTTP Method:
POST

URL:
https://api.podprovider.com/v1/orders

Request Body:
The request body must be in JSON format and include the order's external identifier, shipping method, recipient information, item details, and packing slip information.

Expected JSON Payload Structure

Field Descriptions

• external_id (string): External order ID defined by the client’s system.

• shipping_method (string): Specifies the shipping method (e.g., "STANDARD").

• recipient (object): Details of the recipient.

  • name (string): Full name of the recipient.
  • company (string): Company name of the recipient (optional).
  • address1 (string): Primary street address.
  • address2 (string): Secondary street address (optional).
  • city (string): City of the recipient.
  • state_code (string): State or region code.
  • state_name (string): Full name of the state or region.
  • country_code (string): Country code (ISO format).
  • country_name (string): Full name of the country.
  • zip (string): Postal code.
  • phone (string): Contact phone number.
  • email (string): Contact email address.

• items (array): List of items to be ordered.

  • quantity (integer): Number of units of this item.
  • retail_price (string): Retail price per unit of the item.
  • name (string): Name of the product.
  • variant_id (string): ID of the selected variant.
  • product_id (string): ID of the selected product.
  • external_id (string): External ID for the item defined by the client.
  • files (array): List of print files for this item, each specifying a print area.
    • printArea (string): Location on the product where the design will be printed (e.g., "front", "back").
    • url (string): URL to the design file for this area.

Webhook: Package Shipped Notification

Purpose:
The Package Shipped Webhook is triggered when a package has been shipped. This webhook includes essential tracking and shipping details, and it also provides an optional list of items if the shipment is a partial delivery.

HTTP Method:
POST

Webhook Payload:
This Package Shipped Webhook payload provides all necessary tracking details and supports partial deliveries by specifying only the items shipped in each package. This setup ensures accurate tracking and inventory management for orders shipped in multiple parts.

Example Webhook Payload

Field Descriptions

• external_order_id (string): The external order ID provided by the client when the order was created.
• tracking_number (string): Tracking number for the shipment.
• tracking_url (string): URL for tracking the shipment status via the carrier’s tracking system.
• carrier_code (string): Carrier used for shipping (e.g., "FEDEX").
• items (array, optional): List of items in the shipment, included when there’s a partial delivery.
  • external_id (string): External ID of the item, as specified in the original order.
  • quantity (integer): Quantity of this item included in this shipment.