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

Global Fields

• Product ID (string):
  The unique identifier for the product.

• Product Name (string):
  The name of the product.

• Description (string):
  A detailed description of the product.

Variants (object)

An object containing all available variants of the product. Each variant is identified by a key in the format "Variant: Color / Size". Each variant includes:

• color (string):
  The color of the variant.

• hex_color (string):
  The hexadecimal color code for the variant.

• size (string):
  The size of the variant.

• print_areas (array):
  An array of objects representing the printable areas for the variant. Each object includes:

  • name (string):
    The name of the print area.

  • height_mm (number):
    The height of the print area in millimeters.

  • width_mm (number):
    The width of the print area in millimeters.

  • position_url (string):
    A URL pointing to an image representing the print area.

  • format (string):
    The file format of the print area image.

• prices (object):
  An object containing pricing and delivery information for the variant. It includes:

  • merchant_cost (string):
    The cost to the merchant.

  • suggested_retail_price (string):
    The suggested retail price.

  • shipping (object) - optional :
    An object containing shipping cost details:

    • min_cost (number or null) - optional:
      The minimum shipping cost.

    • max_cost (string or null) - optional:
      The maximum shipping cost.

  • delivery (object) - optional:
    An object containing delivery time details:

    • min_time (string or null) - optional:
      The minimum delivery time.

    • max_time (string or null) - optional:
      The maximum delivery time.
      
      

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.