API Documentation | GW Prints API

Introduction

Welcome to the GW Prints Print-on-Demand API. This API allows you to integrate your e-commerce store with our premium custom metal wall art supply chain. Automate product mockups, order creation, shipment tracking, and fulfillment.

Base URL https://gwprints.com/api/v1

All API requests must be made over HTTPS. Calls made over HTTP will be rejected. The API uses RESTful conventions and returns JSON-encoded responses with standard HTTP response codes.

Currently Supported All responses are in JSON format. We use standard HTTP status codes: 200 for success, 400 for bad requests, 401 for unauthorized, 404 for not found, and 429 for rate limiting.

Authentication

All API requests require an API key passed in the request header. You can obtain your API key from the Client Dashboard.

HTTP Header

X-API-Key: your_api_key_here

// Example cURL request
curl -H "X-API-Key: sk_live_abc123..." \
     https://gwprints.com/api/v1/products
          

Keep your API key secure Never expose your API key in client-side code. Always make API calls from your server backend.

Rate Limits

To ensure fair usage, we enforce the following rate limits per API key:

Plan	Requests/Minute	Requests/Day	Concurrent
Free / Sandbox	30	1,000	5
Standard	120	10,000	20
Enterprise	600	100,000	50

Rate limit headers are included in every response:

Response Headers

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1716883200
          

Error Handling

The API uses standard HTTP status codes and returns error details in JSON format:

Error Response

{
  "error": {
    "code": "INVALID_SKU",
    "message": "The SKU 'ABC-999' does not exist in our catalog.",
    "status": 400
  }
}
          

Code	Meaning
`200`	Success
`201`	Created (order submitted successfully)
`400`	Bad Request — invalid parameters
`401`	Unauthorized — invalid or missing API key
`403`	Forbidden — insufficient permissions
`404`	Not Found — resource doesn't exist
`429`	Too Many Requests — rate limit exceeded
`500`	Internal Server Error

Products

List Categories

GET /categories Retrieve all product categories

Response 200

{
  "data": [
    {
      "id": 1,
      "name": "Matte Finish Series",
      "slug": "matte-finish",
      "product_count": 3,
      "image_url": "https://gwprints.com/images/cat/matte.jpg"
    },
    {
      "id": 2,
      "name": "Glossy Finish Series",
      "slug": "glossy-finish",
      "product_count": 3,
      "image_url": "https://gwprints.com/images/cat/glossy.jpg"
    }
  ],
  "total": 8
}
            

List Products / Product Detail

GET /categories/{id}/products List products in a category

GET /products/{sku} Get single product details, variants & pricing

Orders

Create Order

POST /orders Submit a new drop shipping order

Request Body

Field	Type	Required	Description
external_order_id	string	Required	Your store's order reference ID
shipping_method	string	Optional	standard, expedited (default: standard)
recipient	object	Required	Shipping address object
recipient.name	string	Required	Recipient full name
recipient.phone	string	Required	Phone number with country code
recipient.address_line1	string	Required	Street address
recipient.city	string	Required	City
recipient.state	string	Optional	State/Province
recipient.zip_code	string	Required	Postal code
recipient.country_code	string	Required	ISO 3166-1 alpha-2 code (e.g. US, GB)
items	array	Required	Array of order items
items[].image_url	string	Required	URL to your custom design image
items[].size	string	Optional	Specific size variant (e.g. M, L)
items[].quantity	integer	Required	Quantity (min: 1)
packing_slip	object	Optional	Custom white-label packing slip

Response 201 Created

{
  "data": {
    "order_id": "AMP-2026052800001",
    "external_order_id": "SHOP-20260528-001",
    "status": "confirmed",
    "total_cost": 23.50,
    "currency": "USD",
    "estimated_production_days": 2,
    "created_at": "2026-05-28T10:30:00Z"
  }
}
            

Get Order / List Orders

GET /orders/{order_id} Retrieve a single order with full details

GET /orders?page=1&limit=20&status=shipped List orders with pagination and filters

PUT /orders/{order_id}/cancel Cancel an order (only if status is pending/confirmed)

Pricing

POST /pricing/product Get product cost for a SKU + variant

POST /pricing/shipping Calculate shipping cost by destination + weight

Inventory & Shipping

GET /inventory/{sku} Check real-time stock level for a SKU

GET /orders/{order_id}/shipments Get tracking numbers and carrier info

Webhooks

Subscribe to real-time event notifications. When an event occurs (e.g., order shipped), we'll send an HTTP POST to your registered URL.

Supported Events

Event	Trigger	Payload
`order.confirmed`	Order accepted for production	Order ID, estimated time
`order.in_production`	Production started	Order ID
`order.shipped`	Package dispatched	Order ID, tracking number, carrier
`order.delivered`	Package delivered	Order ID, delivery timestamp
`order.cancelled`	Order cancelled	Order ID, reason
`inventory.low_stock`	Stock below threshold	SKU, remaining quantity

POST /webhooks Register a new webhook subscription

Webhook Payload Example

{
  "event": "order.shipped",
  "timestamp": "2026-05-30T14:22:00Z",
  "data": {
    "order_id": "AMP-2026052800001",
    "external_order_id": "SHOP-20260528-001",
    "tracking_number": "YT2312345678901",
    "carrier": "YunTrack Express",
    "tracking_url": "https://track.example.com/YT2312345678901"
  }
}
          

Account

GET /account/balance Check your current account balance and credit