{ "components": { "headers": { "IdempotentReplayed": { "description": "`true` when this answer is the stored first answer of an Idempotency-Key.", "schema": { "const": "true", "type": "string" } }, "RateLimitLimit": { "description": "The burst size for this key.", "schema": { "type": "integer" } }, "RateLimitRemaining": { "description": "Requests left before the limit (refills at 10 a second).", "schema": { "type": "integer" } }, "RequestId": { "description": "This request's id (`req_…`). Also in every error body.", "schema": { "pattern": "^req_[0-9A-Za-z]+$", "type": "string" } }, "RetryAfter": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "parameters": { "EventId": { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^evt_[0-9A-Za-z]{22}$", "type": "string" } }, "IdempotencyKey": { "description": "Any unique string (a UUID works), 1 to 255 printable characters. Kept 24 hours per brand\nand mode. Same key + same body → the first answer again; same key + another body →\n`409 idempotency_key_reused`; while the first is still running → `409\nidempotency_key_in_use`. A request that failed frees its key.\n", "in": "header", "name": "Idempotency-Key", "schema": { "maxLength": 255, "minLength": 1, "type": "string" } }, "Limit": { "description": "Page size, 1 to 100.", "in": "query", "name": "limit", "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, "OrderId": { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^ord_[0-9A-Za-z]{22}$", "type": "string" } }, "StartingAfter": { "description": "The `next_cursor` of the previous page (the last id you got).", "in": "query", "name": "starting_after", "schema": { "type": "string" } }, "WebhookEndpointId": { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^whk_[0-9A-Za-z]{22}$", "type": "string" } } }, "responses": { "BadRequest": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request is malformed (`parameter_invalid`, `parameter_unknown`, `parameter_missing`, `body_invalid`, `line_item_reference`, `idempotency_key_invalid`, `resource_missing` cursor).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "Conflict": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The change clashes with existing data or the order's state (`external_sku_taken`, `duplicate_external_order_id`, `idempotency_key_reused`, `idempotency_key_in_use`, `order_not_cancellable`, `charge_in_progress`, `order_not_payable`, `test_mode`, `order_state`, `too_many_webhook_endpoints`, `no_webhook_endpoint`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "Forbidden": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key lacks a scope (`missing_scope`), the brand hasn't accepted the Terms of Service (`terms_required`), or a simulation was asked with a live key (`test_mode_only`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "NotFound": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource for your brand (`resource_missing`). Another brand's ids are always 404.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "PaymentFailed": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The card was declined again (`payment_error`, `payment_failed`). The order's `charge` says why.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "RateLimited": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Over 10 requests a second (bursts of 50) for this key, or too many bad keys from your address (`rate_limited`).", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "ServerError": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Our fault (`internal_error`). Safe to retry reads.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "Unauthorized": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No key, or not a valid one (`api_key_missing`, `api_key_invalid`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "Unavailable": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Payments, shipping quotes or webhook set-up are offline for a moment (`payments_unavailable`, `shipping_unavailable`, `webhooks_unavailable`). Retry with the same Idempotency-Key.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "Unprocessable": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Well-formed but can't be done (`address_invalid`, `country_not_supported`, `variant_not_found`, `sku_not_found`, `external_sku_not_found`, `variant_not_available`, `price_unavailable`, `shipping_method_unavailable`, `personalization_unsupported`, `amount_too_small`, `url_not_allowed`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } } }, "schemas": { "Address": { "additionalProperties": false, "properties": { "address1": { "maxLength": 200, "type": "string" }, "address2": { "maxLength": 200, "type": [ "string", "null" ] }, "city": { "maxLength": 100, "type": "string" }, "company": { "maxLength": 120, "type": [ "string", "null" ] }, "country": { "const": "US", "type": "string" }, "email": { "maxLength": 254, "type": [ "string", "null" ] }, "name": { "maxLength": 120, "type": "string" }, "phone": { "maxLength": 40, "type": [ "string", "null" ] }, "postal_code": { "examples": [ "92618" ], "type": "string" }, "state": { "description": "2-letter code.", "examples": [ "CA" ], "type": "string" } }, "required": [ "name", "address1", "city", "state", "postal_code", "country" ], "type": "object" }, "Charge": { "properties": { "amount": { "type": "integer" }, "attempt": { "type": "integer" }, "currency": { "const": "USD", "type": "string" }, "failure_code": { "examples": [ "card_declined", "authentication_required", "no_card" ], "type": [ "string", "null" ] }, "failure_message": { "type": [ "string", "null" ] }, "livemode": { "type": "boolean" }, "next_retry_at": { "format": "date-time", "type": [ "string", "null" ] }, "requires_action": { "description": "Your bank wants you to confirm the card: save it again on the Developers page, then retry.", "type": "boolean" }, "status": { "description": "`simulated` / `not_charged` are test mode (never a real charge); a test order's `failed` is a simulated decline (`simulate/payment_failed`).", "enum": [ "succeeded", "failed", "pending", "not_attempted", "simulated", "not_charged" ], "type": "string" } }, "required": [ "status", "amount", "currency", "livemode" ], "type": "object" }, "Error": { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "examples": [ "variant_not_found" ], "type": "string" }, "message": { "type": "string" }, "param": { "examples": [ "line_items[0].variant_id" ], "type": [ "string", "null" ] }, "request_id": { "examples": [ "req_abc123" ], "type": "string" }, "type": { "enum": [ "authentication_error", "permission_error", "invalid_request_error", "payment_error", "rate_limit_error", "api_error" ], "type": "string" } }, "required": [ "type", "code", "message", "param", "request_id" ], "type": "object" } }, "required": [ "error" ], "type": "object" }, "Event": { "additionalProperties": false, "description": "The envelope of every webhook. `data` by type. `order.shipped`: `{ order_id,\nexternal_order_id, shipment: { id, carrier, service, tracking_number, tracking_url,\nshipped_at, line_items: [{ external_line_id, variant_id, quantity }] }, order_status }`\n(one event per shipment: a partial shipment is its own event). Other `order.*`:\n`{ order_id, external_order_id, order_status, previous_status, reason, occurred_at, order }`\n(`order` = the Order object when the event was made); `order.payment_failed` adds\n`failure_code`, `failure_message`, `next_retry_at`; `order.cancelled` adds\n`refunded_amount`, `currency`. `product.*`: `{ product_id, product_status, product }`\n(`product` = the Product object; null once unpublished). `ping`: `{ webhook_endpoint_id,\nmessage }`.\n", "properties": { "api_version": { "const": "v1", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "data": { "type": "object" }, "id": { "pattern": "^evt_[0-9A-Za-z]{22}$", "type": "string" }, "livemode": { "type": "boolean" }, "type": { "$ref": "#/components/schemas/EventType" } }, "required": [ "id", "type", "created_at", "livemode", "api_version", "data" ], "type": "object" }, "EventList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Event" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "object": { "const": "list", "type": "string" } }, "required": [ "object", "data", "has_more", "next_cursor" ], "type": "object" }, "EventType": { "description": "`ping` is the Developers page's test event; `order.delivered` needs a carrier tracking feed (none yet, so it is never sent today).", "enum": [ "product.published", "product.updated", "product.unpublished", "order.created", "order.paid", "order.payment_failed", "order.on_hold", "order.in_production", "order.shipped", "order.delivered", "order.cancelled", "ping" ], "type": "string" }, "LineItemCreate": { "additionalProperties": false, "description": "Exactly one of variant_id, sku, external_sku.", "properties": { "external_line_id": { "maxLength": 100, "type": [ "string", "null" ] }, "external_sku": { "maxLength": 100, "type": "string" }, "quantity": { "maximum": 10000, "minimum": 1, "type": "integer" }, "retail_price": { "description": "What your customer paid per unit, cents (packing slip / customs). Default: the product's retail price.", "maximum": 1000000, "minimum": 0, "type": [ "integer", "null" ] }, "sku": { "maxLength": 100, "type": "string" }, "variant_id": { "pattern": "^var_[0-9A-Za-z]{22}$", "type": "string" } }, "required": [ "quantity" ], "type": "object" }, "Merchant": { "properties": { "api_version": { "const": "v1", "type": "string" }, "billing": { "properties": { "billing_mode": { "enum": [ "per_order", "prepaid", "internal" ], "type": "string" }, "card_on_file": { "type": "boolean" } }, "required": [ "card_on_file", "billing_mode" ], "type": "object" }, "connection": { "description": "The brand's API connection (\"Connect via API\"), or null.", "oneOf": [ { "type": "null" }, { "properties": { "id": { "pattern": "^con_[0-9A-Za-z]{22}$", "type": "string" }, "status": { "enum": [ "pending", "active", "error", "disconnected" ], "type": "string" }, "type": { "const": "api", "type": "string" } }, "required": [ "id", "type", "status" ], "type": "object" } ] }, "id": { "pattern": "^mer_[0-9A-Za-z]{22}$", "type": "string" }, "key": { "properties": { "kind": { "enum": [ "partner", "catalog" ], "type": "string" }, "livemode": { "type": "boolean" }, "scopes": { "items": { "enum": [ "products:read", "orders:write", "orders:read" ], "type": "string" }, "type": "array" } }, "required": [ "kind", "scopes", "livemode" ], "type": "object" }, "livemode": { "description": "false for a test key: orders are never charged or produced.", "type": "boolean" }, "name": { "type": "string" }, "object": { "const": "merchant", "type": "string" } }, "required": [ "object", "id", "name", "livemode", "api_version", "key", "billing", "connection" ], "type": "object" }, "Order": { "properties": { "cancelled_at": { "format": "date-time", "type": [ "string", "null" ] }, "charge": { "$ref": "#/components/schemas/Charge" }, "charges": { "items": { "$ref": "#/components/schemas/Charge" }, "type": "array" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "const": "USD", "type": "string" }, "external_order_id": { "type": "string" }, "external_order_url": { "type": [ "string", "null" ] }, "id": { "pattern": "^ord_[0-9A-Za-z]{22}$", "type": "string" }, "line_items": { "items": { "properties": { "external_line_id": { "type": [ "string", "null" ] }, "external_sku": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "quantity": { "type": "integer" }, "retail_price": { "type": "integer" }, "sku": { "type": "string" }, "tax": { "type": "integer" }, "total": { "type": "integer" }, "variant_id": { "type": "string" }, "wholesale_price": { "description": "What you pay per unit (snapshot; never recomputed).", "type": "integer" } }, "type": "object" }, "type": "array" }, "livemode": { "type": "boolean" }, "metadata": { "type": "object" }, "number": { "description": "Our order number (what our team calls it).", "type": "integer" }, "object": { "const": "order", "type": "string" }, "packing_slip": { "type": "object" }, "paid_at": { "format": "date-time", "type": [ "string", "null" ] }, "refunds": { "items": { "properties": { "amount": { "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "status": { "type": "string" } }, "type": "object" }, "type": "array" }, "ship_to": { "type": "object" }, "shipments": { "items": { "properties": { "carrier": { "type": "string" }, "id": { "pattern": "^shp_[0-9A-Za-z]{22}$", "type": "string" }, "line_items": { "items": { "type": "object" }, "type": "array" }, "shipped_at": { "format": "date-time", "type": "string" }, "tracking_number": { "type": "string" }, "tracking_url": { "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" }, "shipping": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Shipping" } ] }, "shipping_method": { "description": "What you asked for.", "type": [ "string", "null" ] }, "shipping_total": { "type": "integer" }, "status": { "$ref": "#/components/schemas/OrderStatus" }, "status_reason": { "type": [ "string", "null" ] }, "subtotal": { "type": "integer" }, "tax": { "type": "integer" }, "total": { "type": "integer" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "object", "livemode", "number", "status", "status_reason", "external_order_id", "line_items", "currency", "subtotal", "shipping_total", "tax", "total", "charge", "charges", "refunds", "shipments", "created_at" ], "type": "object" }, "OrderCreate": { "additionalProperties": false, "properties": { "external_order_id": { "maxLength": 100, "minLength": 1, "type": "string" }, "external_order_url": { "format": "uri", "maxLength": 500, "type": [ "string", "null" ] }, "line_items": { "items": { "$ref": "#/components/schemas/LineItemCreate" }, "maxItems": 250, "minItems": 1, "type": "array" }, "metadata": { "description": "Echoed back; at most 4 KB.", "type": [ "object", "null" ] }, "packing_slip": { "additionalProperties": false, "properties": { "message": { "maxLength": 300, "type": [ "string", "null" ] }, "show_prices": { "type": "boolean" } }, "type": [ "object", "null" ] }, "ship_to": { "$ref": "#/components/schemas/Address" }, "shipping_method": { "description": "`standard` (default: the cheapest), `expedited` (the fastest), or one of our service keys (e.g. `ups_ground`).", "type": [ "string", "null" ] } }, "required": [ "external_order_id", "ship_to", "line_items" ], "type": "object" }, "OrderEstimate": { "properties": { "currency": { "const": "USD", "type": "string" }, "line_items": { "items": { "properties": { "external_line_id": { "type": [ "string", "null" ] }, "external_sku": { "type": [ "string", "null" ] }, "in_stock": { "type": "boolean" }, "quantity": { "type": "integer" }, "retail_price": { "type": "integer" }, "sku": { "type": "string" }, "total": { "type": "integer" }, "variant_id": { "type": "string" }, "wholesale_price": { "description": "Per unit at this order's quantity.", "type": "integer" } }, "required": [ "variant_id", "sku", "quantity", "wholesale_price", "retail_price", "total", "in_stock" ], "type": "object" }, "type": "array" }, "livemode": { "type": "boolean" }, "object": { "const": "order_estimate", "type": "string" }, "shipping": { "$ref": "#/components/schemas/Shipping" }, "shipping_total": { "type": "integer" }, "subtotal": { "type": "integer" }, "tax": { "type": "integer" }, "total": { "type": "integer" }, "would_hold": { "properties": { "detail": { "type": "string" }, "reason": { "type": "string" } }, "type": [ "object", "null" ] } }, "required": [ "object", "livemode", "currency", "line_items", "shipping", "subtotal", "shipping_total", "tax", "total", "would_hold" ], "type": "object" }, "OrderEstimateRequest": { "additionalProperties": true, "description": "The OrderCreate body with `external_order_id` optional.", "type": "object" }, "OrderList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Order" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "object": { "const": "list", "type": "string" } }, "required": [ "object", "data", "has_more", "next_cursor" ], "type": "object" }, "OrderShippedData": { "additionalProperties": false, "properties": { "external_order_id": { "type": "string" }, "order_id": { "pattern": "^ord_[0-9A-Za-z]{22}$", "type": "string" }, "order_status": { "$ref": "#/components/schemas/OrderStatus" }, "shipment": { "additionalProperties": false, "properties": { "carrier": { "examples": [ "USPS" ], "type": "string" }, "id": { "pattern": "^shp_[0-9A-Za-z]{22}$", "type": "string" }, "line_items": { "items": { "properties": { "external_line_id": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "variant_id": { "pattern": "^var_[0-9A-Za-z]{22}$", "type": "string" } }, "type": "object" }, "type": "array" }, "service": { "examples": [ "UPS Ground" ], "type": [ "string", "null" ] }, "shipped_at": { "format": "date-time", "type": "string" }, "tracking_number": { "type": "string" }, "tracking_url": { "type": [ "string", "null" ] } }, "required": [ "id", "carrier", "service", "tracking_number", "tracking_url", "shipped_at", "line_items" ], "type": "object" } }, "required": [ "order_id", "external_order_id", "shipment", "order_status" ], "type": "object" }, "OrderStatus": { "description": "received → payment_pending → paid → in_production → partially_shipped → shipped →\ndelivered; payment_failed (retrying), on_hold (status_reason: address_review,\nblank_out_of_stock, payment_failed_final, artwork_issue, manual_review), cancelled,\nrefunded (money returned after shipping).\n", "enum": [ "received", "payment_pending", "paid", "in_production", "partially_shipped", "shipped", "delivered", "payment_failed", "cancelled", "on_hold", "refunded" ], "type": "string" }, "Product": { "properties": { "blank": { "properties": { "brand": { "examples": [ "Sport-Tek" ], "type": [ "string", "null" ] }, "name": { "examples": [ "PosiCharge Competitor Tee" ], "type": "string" }, "style": { "examples": [ "ST350" ], "type": [ "string", "null" ] } }, "required": [ "brand", "style", "name" ], "type": "object" }, "created_at": { "format": "date-time", "type": "string" }, "decoration_method": { "enum": [ "dtg", "dtf", "sublimation", "embroidery", "finished", null ], "type": [ "string", "null" ] }, "description": { "type": "string" }, "id": { "pattern": "^prd_[0-9A-Za-z]{22}$", "type": "string" }, "images": { "description": "Mockups. Links are signed and work for 24 hours; fetch the product again for fresh ones.", "items": { "properties": { "color": { "type": [ "string", "null" ] }, "is_primary": { "type": "boolean" }, "position": { "enum": [ "front", "back" ], "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "url", "position", "color", "is_primary" ], "type": "object" }, "type": "array" }, "object": { "const": "product", "type": "string" }, "published_at": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "enum": [ "published" ], "type": "string" }, "title": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "variants": { "items": { "$ref": "#/components/schemas/Variant" }, "type": "array" } }, "required": [ "id", "object", "status", "title", "description", "blank", "decoration_method", "images", "variants", "published_at", "created_at", "updated_at" ], "type": "object" }, "ProductList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Product" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Pass as `starting_after` for the next page.", "type": [ "string", "null" ] }, "object": { "const": "list", "type": "string" } }, "required": [ "object", "data", "has_more", "next_cursor" ], "type": "object" }, "Shipping": { "properties": { "amount": { "type": "integer" }, "carrier": { "type": "string" }, "days_max": { "type": [ "integer", "null" ] }, "days_min": { "type": [ "integer", "null" ] }, "label": { "type": "string" }, "service": { "examples": [ "ups_ground" ], "type": "string" } }, "type": "object" }, "Variant": { "properties": { "currency": { "const": "USD", "type": "string" }, "external_sku": { "description": "Yours (PATCH /variants/{id}).", "type": [ "string", "null" ] }, "id": { "pattern": "^var_[0-9A-Za-z]{22}$", "type": "string" }, "in_stock": { "description": "The blank is available at the supplier (true when the supplier reports no stock number).", "type": "boolean" }, "object": { "const": "variant", "type": "string" }, "options": { "properties": { "color": { "examples": [ "Navy" ], "type": [ "string", "null" ] }, "size": { "examples": [ "M" ], "type": "string" } }, "required": [ "color", "size" ], "type": "object" }, "product_id": { "pattern": "^prd_[0-9A-Za-z]{22}$", "type": "string" }, "retail_price": { "description": "Your retail price, cents.", "type": "integer" }, "sku": { "description": "Ours, stable.", "examples": [ "PMG-ST350-NAV-M-8F2KA19C0D" ], "type": "string" }, "weight_grams": { "type": [ "integer", "null" ] }, "wholesale_price": { "description": "What you pay us for one unit, cents (before shipping and tax). null while its decoration price isn't set up.", "type": [ "integer", "null" ] } }, "required": [ "id", "object", "product_id", "sku", "external_sku", "options", "retail_price", "wholesale_price", "currency", "weight_grams", "in_stock" ], "type": "object" }, "WebhookEndpoint": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "description": { "type": [ "string", "null" ] }, "disabled_at": { "format": "date-time", "type": [ "string", "null" ] }, "disabled_reason": { "description": "`failing` = turned off after 5 deliveries in a row failed every retry.", "enum": [ "merchant", "failing", "staff", null ], "type": [ "string", "null" ] }, "enabled_events": { "items": { "description": "An event type (not ping), or * for all.", "type": "string" }, "type": "array" }, "failing_since": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "pattern": "^whk_[0-9A-Za-z]{22}$", "type": "string" }, "last_success_at": { "format": "date-time", "type": [ "string", "null" ] }, "livemode": { "type": "boolean" }, "object": { "const": "webhook_endpoint", "type": "string" }, "secret_hint": { "examples": [ "whsec_…a1B2" ], "type": "string" }, "secret_rotated_at": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "enum": [ "active", "disabled" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "object", "livemode", "url", "description", "enabled_events", "status", "disabled_reason", "secret_hint", "created_at", "updated_at" ], "type": "object" }, "WebhookEndpointCreate": { "additionalProperties": false, "properties": { "description": { "maxLength": 200, "type": [ "string", "null" ] }, "enabled_events": { "examples": [ [ "order.shipped", "order.payment_failed" ], [ "*" ] ], "items": { "type": "string" }, "minItems": 1, "type": "array" }, "url": { "examples": [ "https://merchant.example.com/podmfg/webhooks" ], "maxLength": 2048, "type": "string" } }, "required": [ "url", "enabled_events" ], "type": "object" }, "WebhookEndpointList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/WebhookEndpoint" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "object": { "const": "list", "type": "string" } }, "required": [ "object", "data", "has_more", "next_cursor" ], "type": "object" }, "WebhookEndpointUpdate": { "additionalProperties": false, "properties": { "description": { "maxLength": 200, "type": [ "string", "null" ] }, "enabled_events": { "items": { "type": "string" }, "minItems": 1, "type": "array" }, "status": { "enum": [ "active", "disabled" ], "type": "string" }, "url": { "maxLength": 2048, "type": "string" } }, "type": "object" }, "WebhookEndpointWithSecret": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "properties": { "secret": { "description": "The signing secret, shown only in this answer (null in an Idempotency-Key replay).", "pattern": "^whsec_[0-9A-Za-z]{32}$", "type": [ "string", "null" ] } }, "required": [ "secret" ], "type": "object" } ] } }, "securitySchemes": { "bearerAuth": { "description": "`podmfg_test_…` / `podmfg_live_…` (or a Catalog API `podk_…` key, products:read only).", "scheme": "bearer", "type": "http" } } }, "info": { "contact": { "name": "POD Mfg", "url": "https://podmf.com/docs/partner-api" }, "description": "The POD Mfg Partner API lets a brand that doesn't sell on Shopify connect its own system:\nread your published products and variants (with your retail and wholesale prices), map\nyour own SKUs, send orders (we charge your card on file and make them exactly like a\nShopify order), and receive signed webhooks when orders and products change.\n\n**Phase 1:** `GET /me`, `GET /products`, `GET /products/{id}`, `GET /variants/{id}`,\n`PATCH /variants/{id}` (`external_sku` only).\n**Phase 2:** `POST /orders`, `GET /orders`, `GET /orders/{id}`,\n`POST /orders/estimate`, `POST /orders/{id}/cancel`, `POST /orders/{id}/retry_payment`.\n**Phase 3:** `/webhook_endpoints` (create, list, get, update, delete, rotate the secret),\n`GET /events`, `GET /events/{id}`, `POST /events/{id}/resend`, and the webhooks themselves\n(see `webhooks`).\n**Phase 4 (this version of the spec):** test-mode simulations\n`POST /orders/{id}/simulate/ship`, `…/simulate/payment_failed`, `…/simulate/cancel`.\n\n**Start here:** the quickstart \"Your first order in 15 minutes\" at\nhttps://podmf.com/docs/partner-api-quickstart (test key, products, order, webhook,\nsignature check).\n\n**Webhooks.** Add an endpoint (here or on the Developers page) and pick the events it wants\n(`[\"*\"]` = all). Live endpoints must be https; every endpoint must be a public address (no\nprivate, loopback, link-local or internal hosts; redirects are not followed). Each delivery is\na `POST` of the event envelope `{ id, type, created_at, livemode, api_version, data }` with\n`PODMFG-Signature: t=,v1=.\" keyed with your\nendpoint's secret>`, `PODMFG-Event-Id` and `PODMFG-Event-Type`. Verify the signature over the\nraw body and reject a `t` more than 5 minutes off (samples:\nhttps://podmf.com/docs/partner-api-quickstart#verify). Answer any 2xx within 10 seconds; anything else is retried\nafter 1 m, 5 m, 30 m, 2 h, 6 h, 12 h, 24 h and 24 h (9 tries, about 3 days). After that the\ndelivery has failed: we email you and it shows on the Developers page, where you (or\n`POST /events/{id}/resend`) can send it again. An endpoint whose deliveries fail for good 5\ntimes in a row is turned off (we email you). Delivery is at least once: dedupe on the event\n`id`. Order isn't guaranteed: use `order_status` and the times in `data`. Test-mode events\n(test orders) go only to test endpoints; product events are sent in both modes. Events are\nkept 30 days (`GET /events` to backfill).\n\n**Orders.** A live order is charged at once (wholesale + shipping + tax) to the card you saved\non the Developers page, then goes to production. A declined card leaves the order\n`payment_failed`; we email your billing contact and retry automatically after 1, 6 and 24\nhours, then hold it (`on_hold`, `payment_failed_final`): fix the card and call\n`retry_payment`. Nothing unpaid is ever made. A test-key order is never charged and never\nmade: its payment is simulated (`status: paid`, `charge.status: simulated`); the `simulate`\nendpoints (Sandbox) then ship it, fail its payment or cancel it, with the same webhooks a live\norder gets. Send\n`Idempotency-Key` on every POST: a retry with the same key and body returns the first answer\n(`Idempotent-Replayed: true`) and never makes a second order or charge. `external_order_id`\nis unique per brand and mode (`409 duplicate_external_order_id`). US addresses only\n(`422 country_not_supported`); an address we can't ship to is `422 address_invalid`; one\na person should check (no house number, territories, APO/FPO) is accepted and held\n(`on_hold`, `address_review`); a blank out of stock at the supplier holds the order\n(`blank_out_of_stock`). Sales tax is not charged in v1 (`tax: 0`).\n\n**Keys.** Make keys on the Developers page in POD Mfg. Send one as\n`Authorization: Bearer podmfg_test_…` (test mode: orders are never charged or produced) or\n`podmfg_live_…`. A key is shown once; we keep only a hash. Keys made for the Catalog API\n(`podk_…`) keep working here with the `products:read` scope.\n\n**Conventions.** JSON only. Times are ISO 8601 UTC. Money is integer cents with a\n`currency` (`USD`). Ids are prefixed strings (`prd_`, `var_`, `ord_`, `shp_`, `evt_`,\n`whk_`, `mer_`, `con_`). Lists are cursor-paginated: `?limit=50&starting_after=` →\n`{ data, has_more, next_cursor }`. Every response carries `X-Request-Id`; include it when\nyou contact us. Rate limit: 10 requests a second per key, bursts of 50\n(`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After` on 429). Within `v1`, changes\nare additive only: ignore fields you don't know.\n", "summary": "Sell POD Mfg products from your own store, site or ERP.", "title": "POD Mfg Partner API", "version": "v1" }, "openapi": "3.1.0", "paths": { "/events": { "get": { "description": "The events of the key's mode, newest first, exactly as they were (or would have been)\nsent: to poll, or to backfill after your endpoint was down. Kept 30 days. Needs\n`orders:read`.\n", "operationId": "listEvents", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" }, { "in": "query", "name": "type", "schema": { "$ref": "#/components/schemas/EventType" } }, { "description": "Only events created at or after this time (ISO 8601).", "in": "query", "name": "since", "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventList" } } }, "description": "A page of events.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "summary": "List events", "tags": [ "Webhooks" ] } }, "/events/{id}": { "get": { "description": "The envelope exactly as sent. Needs `orders:read`.", "operationId": "getEvent", "parameters": [ { "$ref": "#/components/parameters/EventId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } }, "description": "The event.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "summary": "One event", "tags": [ "Webhooks" ] } }, "/events/{id}/resend": { "post": { "description": "To one endpoint (`webhook_endpoint_id`) or to every active endpoint of the key's mode that\nwants the event's type. Each delivery starts the retry schedule again; it goes out within\nseconds. `409 no_webhook_endpoint` when no active endpoint wants it. Needs `orders:write`.\n", "operationId": "resendEvent", "parameters": [ { "$ref": "#/components/parameters/EventId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "webhook_endpoint_id": { "pattern": "^whk_[0-9A-Za-z]{22}$", "type": "string" } }, "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "event_id": { "pattern": "^evt_[0-9A-Za-z]{22}$", "type": "string" }, "object": { "const": "event_resend", "type": "string" }, "webhook_endpoints": { "items": { "pattern": "^whk_[0-9A-Za-z]{22}$", "type": "string" }, "type": "array" } }, "required": [ "object", "event_id", "webhook_endpoints" ], "type": "object" } } }, "description": "Queued.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "summary": "Send an event again", "tags": [ "Webhooks" ] } }, "/me": { "get": { "description": "Your brand, the key's mode and scopes, and whether a card is on file.", "operationId": "getMe", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Merchant" } } }, "description": "The merchant behind the key.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "summary": "Who this key is (a connection test)", "tags": [ "Account" ] } }, "/orders": { "get": { "description": "Your orders in the key's mode (a test key sees test orders only), newest first. Needs `orders:read`.", "operationId": "listOrders", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" }, { "in": "query", "name": "status", "schema": { "$ref": "#/components/schemas/OrderStatus" } }, { "in": "query", "name": "external_order_id", "schema": { "maxLength": 100, "type": "string" } }, { "description": "Only orders created at or after this time (ISO 8601).", "in": "query", "name": "created_since", "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderList" } } }, "description": "A page of orders.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "summary": "List orders", "tags": [ "Orders" ] }, "post": { "description": "Needs `orders:write`. Each line names exactly one of `variant_id`, `sku` (ours) or\n`external_sku` (yours); unknown fields are refused. Answers `201` with the order, its\n`status` and the `charge` result: a live order is charged now (`charge.status`\n`succeeded` → `status: paid`; `failed` → `status: payment_failed`, retried\nautomatically; `pending` → Stripe is still working on it). A held order\n(`on_hold`) isn't charged until we release it.\n", "operationId": "createOrder", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "example": { "external_order_id": "1042", "external_order_url": "https://merchant-admin.example.com/orders/1042", "line_items": [ { "external_line_id": "li_1", "quantity": 2, "retail_price": 2800, "variant_id": "var_31xaQ8dZr0mJxWb7fKp2sT" } ], "metadata": { "anything": "merchant wants echoed back" }, "packing_slip": { "message": "Thanks for supporting the team!", "show_prices": false }, "ship_to": { "address1": "123 Main St", "address2": "Apt 4", "city": "Irvine", "company": null, "country": "US", "email": "jane@example.com", "name": "Jane Smith", "phone": "+19495551234", "postal_code": "92618", "state": "CA" }, "shipping_method": "standard" }, "schema": { "$ref": "#/components/schemas/OrderCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "description": "The order.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "summary": "Create an order", "tags": [ "Orders" ] } }, "/orders/estimate": { "post": { "description": "The same body as `POST /orders` (`external_order_id` optional). Answers the wholesale\ntotal, shipping and tax, and whether the order would be held. Nothing is stored or\ncharged. Needs `orders:write` or `orders:read`.\n", "operationId": "estimateOrder", "requestBody": { "content": { "application/json": { "example": { "line_items": [ { "quantity": 12, "sku": "PMG-ST350-NAV-M-8F2KA19C0D" } ], "ship_to": { "address1": "123 Main St", "city": "Irvine", "country": "US", "name": "Jane Smith", "postal_code": "92618", "state": "CA" }, "shipping_method": "standard" }, "schema": { "$ref": "#/components/schemas/OrderEstimateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderEstimate" } } }, "description": "The estimate.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "summary": "Price an order without making it", "tags": [ "Orders" ] } }, "/orders/{id}": { "get": { "description": "Status, the price snapshot, charges, refunds and shipments. Needs `orders:read`.", "operationId": "getOrder", "parameters": [ { "$ref": "#/components/parameters/OrderId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "description": "The order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "summary": "One order", "tags": [ "Orders" ] } }, "/orders/{id}/cancel": { "post": { "description": "Allowed until the order is `in_production`; a paid order is refunded in full. Cancelling\na cancelled order answers it again. After production starts: `409 order_not_cancellable`\n(contact us). Needs `orders:write`.\n", "operationId": "cancelOrder", "parameters": [ { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "reason": { "maxLength": 200, "minLength": 1, "type": "string" } }, "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "description": "The cancelled order (with its refund).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "summary": "Cancel an order before production", "tags": [ "Orders" ] } }, "/orders/{id}/retry_payment": { "post": { "description": "For a live order that is `payment_failed`, or `on_hold` with `payment_failed_final`\n(e.g. after you saved a new card). Answers the paid order, or `402 payment_failed` when\nthe card is declined again. Test orders: a simulated failure\n(`POST /orders/{id}/simulate/payment_failed`) retries into simulated success\n(`order.paid`); any other test order is `409 test_mode`. Needs `orders:write`.\n", "operationId": "retryOrderPayment", "parameters": [ { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "description": "The order after the charge.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentFailed" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "summary": "Charge a failed order again", "tags": [ "Orders" ] } }, "/orders/{id}/simulate/cancel": { "post": { "description": "Cancels the order as POD Mfg staff would (`reason: cancelled_by_pod_mfg`) and sends\n`order.cancelled`, so you can test an order you did not cancel yourself. Allowed before\nproduction, like `POST /orders/{id}/cancel`.\n**Test keys and test orders only** (a live key: `403 test_mode_only`; a live order's id\nis not found with a test key). No body. Needs `orders:write`. Wrong state:\n`409 order_state`.\n", "operationId": "simulateOrderCancelled", "parameters": [ { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "description": "The test order after the simulation.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "summary": "Test mode: POD Mfg cancels a test order", "tags": [ "Sandbox" ] } }, "/orders/{id}/simulate/payment_failed": { "post": { "description": "The simulated payment fails: the order becomes `payment_failed` (`status_reason:\ncard_declined`, `charge.status: failed`) and `order.payment_failed` is sent. Then\n`POST /orders/{id}/retry_payment` simulates success (`order.paid`), or cancel it. No card\nis involved. Needs the order `paid`.\n**Test keys and test orders only** (a live key: `403 test_mode_only`; a live order's id\nis not found with a test key). No body. Needs `orders:write`. Wrong state:\n`409 order_state`.\n", "operationId": "simulateOrderPaymentFailed", "parameters": [ { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "description": "The test order after the simulation.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "summary": "Test mode: fail a test order's payment", "tags": [ "Sandbox" ] } }, "/orders/{id}/simulate/ship": { "post": { "description": "Makes one simulated parcel for the whole order (carrier USPS, service Ground Advantage, a\nfake tracking number `TEST` + 16 digits) and moves the order to `shipped`. An\n`order.shipped` webhook goes to your **test** endpoints through the same pipeline (signing,\nretries, delivery log) as a real shipment. Nothing is made or shipped. Needs the order\n`paid`.\n**Test keys and test orders only** (a live key: `403 test_mode_only`; a live order's id\nis not found with a test key). No body. Needs `orders:write`. Wrong state:\n`409 order_state`.\n", "operationId": "simulateOrderShipped", "parameters": [ { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "description": "The test order after the simulation.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "summary": "Test mode: mark a test order shipped", "tags": [ "Sandbox" ] } }, "/products": { "get": { "description": "Your published products, newest first, each with its variants. Needs `products:read`.\nUnknown query parameters are refused (`400 parameter_unknown`).\n", "operationId": "listProducts", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" }, { "description": "Only products changed at or after this time (ISO 8601).", "in": "query", "name": "updated_since", "schema": { "format": "date-time", "type": "string" } }, { "description": "Only `published` is available.", "in": "query", "name": "status", "schema": { "enum": [ "published" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductList" } } }, "description": "A page of products.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "summary": "List published products", "tags": [ "Products" ] } }, "/products/{id}": { "get": { "description": "The product with its variants, mockup images and prices. Needs `products:read`.", "operationId": "getProduct", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^prd_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }, "description": "The product.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "summary": "One published product", "tags": [ "Products" ] } }, "/variants/{id}": { "get": { "description": "A variant of a published product. Needs `products:read`.", "operationId": "getVariant", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Variant" } } }, "description": "The variant.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "summary": "One variant", "tags": [ "Products" ] }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^var_[0-9A-Za-z]{22}$", "type": "string" } } ], "patch": { "description": "The only change allowed on products in v1. `external_sku` is unique among your variants\n(`409 external_sku_taken`); `null` clears it. Orders may name a variant by its\n`id`, our `sku` or your `external_sku`. Needs `orders:write`.\n", "operationId": "updateVariant", "requestBody": { "content": { "application/json": { "example": { "external_sku": "TEAM-TEE-NAVY-M" }, "schema": { "additionalProperties": false, "properties": { "external_sku": { "description": "Printable ASCII; surrounding spaces are trimmed.", "maxLength": 100, "minLength": 1, "type": [ "string", "null" ] } }, "required": [ "external_sku" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Variant" } } }, "description": "The updated variant.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "summary": "Set your own SKU for a variant", "tags": [ "Products" ] } }, "/webhook_endpoints": { "get": { "description": "Your endpoints in the key's mode, newest first. Never the secrets. Needs `orders:write`.", "operationId": "listWebhookEndpoints", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointList" } } }, "description": "A page of endpoints.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "summary": "List webhook endpoints", "tags": [ "Webhooks" ] }, "post": { "description": "In the key's mode (a test key makes a test endpoint). Live endpoints must be https; the\nhost must be a public address. Answers the endpoint with its signing `secret`, the only\ntime it is shown (a replay with the same Idempotency-Key answers `secret: null`). At most\n16 endpoints per mode. Needs `orders:write`.\n", "operationId": "createWebhookEndpoint", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "example": { "description": "Order system", "enabled_events": [ "order.shipped", "order.payment_failed", "order.cancelled" ], "url": "https://merchant.example.com/podmfg/webhooks" }, "schema": { "$ref": "#/components/schemas/WebhookEndpointCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" } } }, "description": "The endpoint, with its secret.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "summary": "Add a webhook endpoint", "tags": [ "Webhooks" ] } }, "/webhook_endpoints/{id}": { "delete": { "description": "Nothing more is sent to it; deliveries still waiting end as failed. Needs `orders:write`.", "operationId": "deleteWebhookEndpoint", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "const": true, "type": "boolean" }, "id": { "pattern": "^whk_[0-9A-Za-z]{22}$", "type": "string" }, "object": { "const": "webhook_endpoint", "type": "string" } }, "required": [ "id", "object", "deleted" ], "type": "object" } } }, "description": "Deleted.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "summary": "Delete a webhook endpoint", "tags": [ "Webhooks" ] }, "get": { "description": "Needs `orders:write`.", "operationId": "getWebhookEndpoint", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "description": "The endpoint.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "summary": "One webhook endpoint", "tags": [ "Webhooks" ] }, "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" } ], "patch": { "description": "Any of `url`, `enabled_events`, `description` (null clears it), `status` (`active` /\n`disabled`). Turning an endpoint back on forgets its failures and resumes deliveries that\nwere waiting. Needs `orders:write`.\n", "operationId": "updateWebhookEndpoint", "requestBody": { "content": { "application/json": { "example": { "enabled_events": [ "*" ] }, "schema": { "$ref": "#/components/schemas/WebhookEndpointUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "description": "The endpoint.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "summary": "Change a webhook endpoint", "tags": [ "Webhooks" ] } }, "/webhook_endpoints/{id}/rotate_secret": { "post": { "description": "A new secret, shown once in this answer; deliveries are signed with it from now on (the old\none stops at once; update your handler first, or accept both while you switch). Needs\n`orders:write`.\n", "operationId": "rotateWebhookSecret", "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" } } }, "description": "The endpoint, with its new secret.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "summary": "Rotate an endpoint's signing secret", "tags": [ "Webhooks" ] } } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "description": "Production (test and live keys both use it; the key decides the mode)", "url": "https://app.podmf.com/api/v1" } ], "tags": [ { "name": "Account" }, { "name": "Products" }, { "name": "Orders" }, { "name": "Webhooks" }, { "description": "Test-mode simulations, so you can build your webhook handler end to end before going live.", "name": "Sandbox" } ], "webhooks": { "order.events": { "post": { "operationId": "webhookOrderEvent", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } }, "required": true }, "responses": { "200": { "description": "Any 2xx within 10 seconds is a success." } }, "summary": "order.created, order.paid, order.payment_failed, order.on_hold, order.in_production, order.delivered, order.cancelled" } }, "order.shipped": { "post": { "operationId": "webhookOrderShipped", "parameters": [ { "in": "header", "name": "PODMFG-Signature", "required": true, "schema": { "examples": [ "t=1791400925,v1=5257a869…" ], "type": "string" } }, { "in": "header", "name": "PODMFG-Event-Id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "PODMFG-Event-Type", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "properties": { "data": { "$ref": "#/components/schemas/OrderShippedData" } }, "type": "object" } ] } } }, "required": true }, "responses": { "200": { "description": "Any 2xx within 10 seconds is a success." } }, "summary": "A shipment was recorded (one per shipment)" } }, "product.events": { "post": { "operationId": "webhookProductEvent", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } }, "required": true }, "responses": { "200": { "description": "Any 2xx within 10 seconds is a success." } }, "summary": "product.published, product.updated, product.unpublished (sent in both modes)" } } } }