{
    "openapi": "3.1.0",
    "info": {
        "title": "Ship a Postcard API",
        "version": "1.0.0",
        "description": "Print and mail physical postcards to US addresses. Postcards created through the API are verified (address, message, image), billed together every night at 23:59 UTC to the workspace owner's saved card with volume pricing, then printed and mailed. Senders can be anywhere; recipients must have a US address. Runnable examples in cURL, Node.js, PHP and Python: https://github.com/shipapostcard/shipapostcard-api-examples",
        "termsOfService": "https://shipapostcard.com/developer-agreement",
        "license": {
            "name": "Proprietary",
            "url": "https://shipapostcard.com/developer-agreement"
        },
        "contact": {
            "email": "support@shipapostcard.com",
            "url": "https://shipapostcard.com/developer/docs"
        }
    },
    "externalDocs": {
        "description": "API documentation",
        "url": "https://shipapostcard.com/developer/docs"
    },
    "servers": [
        {
            "url": "https://shipapostcard.com/api/v1"
        }
    ],
    "security": [
        {
            "bearerAuth": []
        }
    ],
    "paths": {
        "/postcards": {
            "post": {
                "operationId": "createPostcard",
                "summary": "Create a postcard",
                "description": "Queues a postcard for the nightly batch. It can be cancelled until the batch picks it up.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/PostcardCreate"
                            },
                            "example": {
                                "message": "Thanks for your order! Enjoy 20% off your next one with THANKS20.",
                                "recipient_details": {
                                    "name": "Jane Doe",
                                    "address_line1": "185 Berry St",
                                    "city": "San Francisco",
                                    "state": "CA",
                                    "zip": "94107",
                                    "country": "US"
                                },
                                "design_details": {
                                    "image_url": "https://example.com/postcard-front.jpg",
                                    "size": "4x6",
                                    "orientation": "landscape"
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Postcard queued.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PostcardCreated"
                                },
                                "example": {
                                    "id": "sap_order_94812",
                                    "status": "pending_batch",
                                    "amount": 2.25,
                                    "message": "Postcard queued for daily batch processing."
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "422": {
                        "description": "Invalid parameters.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ValidationFailed"
                                },
                                "example": {
                                    "error": "Validation Failed",
                                    "details": {
                                        "recipient_details.zip": [
                                            "The recipient details.zip field format is invalid."
                                        ]
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "get": {
                "operationId": "listPostcards",
                "summary": "List the postcards of your workspace",
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "10 postcards per page, newest first.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PostcardPage"
                                },
                                "example": {
                                    "current_page": 1,
                                    "data": [
                                        {
                                            "id": "sap_order_94812",
                                            "status": "in_transit",
                                            "amount": 2.25,
                                            "message": "Thanks for your order! Enjoy 20% off your next one with THANKS20.",
                                            "recipient_details": {
                                                "name": "Jane Doe",
                                                "address_line1": "185 Berry St",
                                                "city": "San Francisco",
                                                "state": "CA",
                                                "zip": "94107",
                                                "country": "US"
                                            },
                                            "design_details": {
                                                "image_url": "https://example.com/postcard-front.jpg",
                                                "size": "4x6",
                                                "orientation": "landscape"
                                            },
                                            "tracking": {
                                                "expected_delivery_date": "2026-10-22",
                                                "events": [
                                                    {
                                                        "event": "sent_to_printer",
                                                        "timestamp": "2026-10-16 23:59:41"
                                                    },
                                                    {
                                                        "event": "postcard.in_transit",
                                                        "timestamp": "2026-10-18 09:12:05"
                                                    }
                                                ]
                                            },
                                            "created_at": "2026-10-16T14:03:11+00:00",
                                            "updated_at": "2026-10-18T09:12:05+00:00"
                                        }
                                    ],
                                    "per_page": 10,
                                    "total": 1,
                                    "next_page_url": null
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                }
            }
        },
        "/postcards/{id}": {
            "get": {
                "operationId": "getPostcard",
                "summary": "Retrieve a postcard",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id returned on creation (\"sap_order_123\") or the plain number.",
                        "schema": {
                            "type": "string",
                            "pattern": "^(sap_order_)?\\d+$"
                        },
                        "example": "sap_order_94812"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The postcard.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Postcard"
                                },
                                "example": {
                                    "id": "sap_order_94812",
                                    "status": "in_transit",
                                    "amount": 2.25,
                                    "message": "Thanks for your order! Enjoy 20% off your next one with THANKS20.",
                                    "recipient_details": {
                                        "name": "Jane Doe",
                                        "address_line1": "185 Berry St",
                                        "city": "San Francisco",
                                        "state": "CA",
                                        "zip": "94107",
                                        "country": "US"
                                    },
                                    "design_details": {
                                        "image_url": "https://example.com/postcard-front.jpg",
                                        "size": "4x6",
                                        "orientation": "landscape"
                                    },
                                    "tracking": {
                                        "expected_delivery_date": "2026-10-22",
                                        "events": [
                                            {
                                                "event": "sent_to_printer",
                                                "timestamp": "2026-10-16 23:59:41"
                                            },
                                            {
                                                "event": "postcard.in_transit",
                                                "timestamp": "2026-10-18 09:12:05"
                                            }
                                        ]
                                    },
                                    "created_at": "2026-10-16T14:03:11+00:00",
                                    "updated_at": "2026-10-18T09:12:05+00:00"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "description": "Not found in your workspace."
                    }
                }
            },
            "delete": {
                "operationId": "cancelPostcard",
                "summary": "Cancel a postcard",
                "description": "Allowed while the status is pending_batch or ready_for_batch.",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "The id returned on creation (\"sap_order_123\") or the plain number.",
                        "schema": {
                            "type": "string",
                            "pattern": "^(sap_order_)?\\d+$"
                        },
                        "example": "sap_order_94812"
                    }
                ],
                "responses": {
                    "204": {
                        "description": "Cancelled."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Already being billed, printed or mailed."
                    },
                    "404": {
                        "description": "Not found in your workspace."
                    }
                }
            }
        },
        "/user": {
            "get": {
                "operationId": "getCurrentUser",
                "summary": "Check your API key",
                "responses": {
                    "200": {
                        "description": "The user the key belongs to.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "id": 7,
                                    "name": "Jane Doe",
                                    "email": "jane@example.com"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                }
            }
        }
    },
    "webhooks": {
        "postcard.created": {
            "post": {
                "operationId": "onPostcardCreated",
                "summary": "Postcard Created",
                "description": "Signed with the endpoint secret: ShipAPostcard-Signature: t={timestamp},v1={hex HMAC-SHA256 of \"{timestamp}.{raw body}\"}.",
                "parameters": [
                    {
                        "name": "ShipAPostcard-Signature",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "ShipAPostcard-Event-Id",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/WebhookEvent"
                            },
                            "example": {
                                "id": "evt_8sKq2Lm4",
                                "type": "postcard.created",
                                "created_at": 1792159391,
                                "data": {
                                    "id": "sap_order_94812",
                                    "status": "pending_batch",
                                    "amount": 2.25
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "2XX": {
                        "description": "Received. Any other status is retried (3 attempts)."
                    }
                }
            }
        },
        "postcard.sent_to_printer": {
            "post": {
                "operationId": "onPostcardSentToPrinter",
                "summary": "Sent to Printer",
                "description": "Signed with the endpoint secret: ShipAPostcard-Signature: t={timestamp},v1={hex HMAC-SHA256 of \"{timestamp}.{raw body}\"}.",
                "parameters": [
                    {
                        "name": "ShipAPostcard-Signature",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "ShipAPostcard-Event-Id",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/WebhookEvent"
                            },
                            "example": {
                                "id": "evt_8sKq2Lm4",
                                "type": "postcard.sent_to_printer",
                                "created_at": 1792159391,
                                "data": {
                                    "batch_id": "sap_batch_311",
                                    "status": "sent_to_printer",
                                    "total_cards_processed": 2,
                                    "total_cards_failed": 0,
                                    "successful_order_ids": [
                                        "sap_order_94812",
                                        "sap_order_94813"
                                    ]
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "2XX": {
                        "description": "Received. Any other status is retried (3 attempts)."
                    }
                }
            }
        },
        "postcard.delivered": {
            "post": {
                "operationId": "onPostcardDelivered",
                "summary": "Delivered to Mailbox",
                "description": "Signed with the endpoint secret: ShipAPostcard-Signature: t={timestamp},v1={hex HMAC-SHA256 of \"{timestamp}.{raw body}\"}.",
                "parameters": [
                    {
                        "name": "ShipAPostcard-Signature",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "ShipAPostcard-Event-Id",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/WebhookEvent"
                            },
                            "example": {
                                "id": "evt_8sKq2Lm4",
                                "type": "postcard.delivered",
                                "created_at": 1792159391,
                                "data": {
                                    "id": "sap_order_94812",
                                    "status": "delivered",
                                    "lob_id": "psc_5c002b86ce47537a",
                                    "delivered_at": "2026-10-22T14:03:11+00:00"
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "2XX": {
                        "description": "Received. Any other status is retried (3 attempts)."
                    }
                }
            }
        },
        "postcard.failed": {
            "post": {
                "operationId": "onPostcardFailed",
                "summary": "Delivery Failed",
                "description": "Signed with the endpoint secret: ShipAPostcard-Signature: t={timestamp},v1={hex HMAC-SHA256 of \"{timestamp}.{raw body}\"}.",
                "parameters": [
                    {
                        "name": "ShipAPostcard-Signature",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "ShipAPostcard-Event-Id",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/WebhookEvent"
                            },
                            "example": {
                                "id": "evt_8sKq2Lm4",
                                "type": "postcard.failed",
                                "created_at": 1792159391,
                                "data": {
                                    "id": "sap_order_94812",
                                    "status": "invalid_address",
                                    "reason": "The address could not be verified."
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "2XX": {
                        "description": "Received. Any other status is retried (3 attempts)."
                    }
                }
            }
        },
        "batch.payment_failed": {
            "post": {
                "operationId": "onBatchPaymentFailed",
                "summary": "Batch Payment Failed (Billing Error)",
                "description": "Signed with the endpoint secret: ShipAPostcard-Signature: t={timestamp},v1={hex HMAC-SHA256 of \"{timestamp}.{raw body}\"}.",
                "parameters": [
                    {
                        "name": "ShipAPostcard-Signature",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "ShipAPostcard-Event-Id",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/WebhookEvent"
                            },
                            "example": {
                                "id": "evt_8sKq2Lm4",
                                "type": "batch.payment_failed",
                                "created_at": 1792159391,
                                "data": {
                                    "event": "batch.payment_failed",
                                    "batch_id": "sap_batch_311",
                                    "message": "The daily batch payment declined. API postcard fulfillment is paused.",
                                    "stripe_error": "Your card was declined.",
                                    "declined_amount": 4.5,
                                    "affected_cards": 2,
                                    "action_required": "Please update your default payment method in the dashboard."
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "2XX": {
                        "description": "Received. Any other status is retried (3 attempts)."
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "description": "API key created in the Developer Hub."
            }
        },
        "responses": {
            "Unauthenticated": {
                "description": "Missing, invalid or revoked API key.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        },
                        "example": {
                            "success": false,
                            "message": "Unauthenticated",
                            "errors": null,
                            "error_code": "AUTH_ERROR"
                        }
                    }
                }
            }
        },
        "schemas": {
            "PostcardCreate": {
                "type": "object",
                "required": [
                    "message",
                    "recipient_details",
                    "design_details"
                ],
                "properties": {
                    "message": {
                        "description": "Text printed on the back of the card.",
                        "type": "string",
                        "maxLength": 350
                    },
                    "recipient_details": {
                        "type": "object",
                        "description": "Recipient address. Recipients must be in the United States.",
                        "required": [
                            "name",
                            "address_line1",
                            "city",
                            "state",
                            "zip",
                            "country"
                        ],
                        "properties": {
                            "name": {
                                "description": "Recipient name.",
                                "type": "string",
                                "maxLength": 40
                            },
                            "address_line1": {
                                "description": "Street address.",
                                "type": "string",
                                "maxLength": 64
                            },
                            "city": {
                                "description": "City.",
                                "type": "string",
                                "maxLength": 200
                            },
                            "state": {
                                "description": "Two-letter US state code, e.g. CA.",
                                "type": "string",
                                "minLength": 2,
                                "maxLength": 2,
                                "pattern": "^[a-zA-Z]{2}$"
                            },
                            "zip": {
                                "description": "ZIP code: 12345 or 12345-6789.",
                                "type": "string",
                                "pattern": "^\\d{5}(-\\d{4})?$"
                            },
                            "country": {
                                "description": "Two-letter country code. Use US.",
                                "type": "string",
                                "maxLength": 2
                            }
                        }
                    },
                    "design_details": {
                        "type": "object",
                        "description": "Front image and card format.",
                        "required": [
                            "image_url"
                        ],
                        "properties": {
                            "image_url": {
                                "description": "Publicly accessible URL of a high-resolution JPG or PNG (under 20 MB).",
                                "type": "string",
                                "format": "uri"
                            },
                            "size": {
                                "description": "Card size in inches. Defaults to 4x6.",
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "enum": [
                                    "4x6",
                                    "5x7",
                                    "6x9",
                                    null
                                ]
                            },
                            "orientation": {
                                "description": "Front image orientation. Defaults to landscape.",
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "enum": [
                                    "landscape",
                                    "portrait",
                                    null
                                ]
                            }
                        }
                    }
                }
            },
            "PostcardCreated": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "sap_order_94812"
                    },
                    "status": {
                        "type": "string",
                        "example": "pending_batch"
                    },
                    "amount": {
                        "type": "number",
                        "description": "Single-card price in USD; the final price is set by volume in the nightly batch."
                    },
                    "message": {
                        "type": "string"
                    }
                }
            },
            "Postcard": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "sap_order_94812"
                    },
                    "status": {
                        "type": "string",
                        "description": "pending_batch, ready_for_batch, processing_payment, paid, sent_to_printer, in_transit, delivered; or failed, payment_failed, invalid_address, flagged_for_review, image_download_failed."
                    },
                    "amount": {
                        "type": [
                            "number",
                            "null"
                        ],
                        "description": "Price in USD, as in the create response."
                    },
                    "message": {
                        "type": "string"
                    },
                    "recipient_details": {
                        "type": "object",
                        "properties": {
                            "name": {
                                "type": "string"
                            },
                            "address_line1": {
                                "type": "string"
                            },
                            "address_line2": {
                                "type": "string"
                            },
                            "city": {
                                "type": "string"
                            },
                            "state": {
                                "type": "string"
                            },
                            "zip": {
                                "type": "string"
                            },
                            "country": {
                                "type": "string"
                            }
                        }
                    },
                    "design_details": {
                        "type": "object",
                        "properties": {
                            "image_url": {
                                "type": "string"
                            },
                            "size": {
                                "type": "string"
                            },
                            "orientation": {
                                "type": "string"
                            }
                        }
                    },
                    "tracking": {
                        "type": "object",
                        "properties": {
                            "expected_delivery_date": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "description": "Set once the card is sent to the printer."
                            },
                            "events": {
                                "type": "array",
                                "description": "Oldest first, e.g. sent_to_printer, postcard.in_transit, postcard.delivered.",
                                "items": {
                                    "type": "object",
                                    "properties": {
                                        "event": {
                                            "type": "string"
                                        },
                                        "timestamp": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "PostcardPage": {
                "type": "object",
                "properties": {
                    "current_page": {
                        "type": "integer"
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Postcard"
                        }
                    },
                    "per_page": {
                        "type": "integer"
                    },
                    "total": {
                        "type": "integer"
                    },
                    "next_page_url": {
                        "type": [
                            "string",
                            "null"
                        ]
                    }
                }
            },
            "ValidationFailed": {
                "type": "object",
                "properties": {
                    "error": {
                        "type": "string",
                        "example": "Validation Failed"
                    },
                    "details": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "array",
                            "items": {
                                "type": "string"
                            }
                        }
                    }
                }
            },
            "Error": {
                "type": "object",
                "properties": {
                    "success": {
                        "type": "boolean"
                    },
                    "message": {
                        "type": "string"
                    },
                    "errors": {
                        "description": "Field errors, or null."
                    },
                    "error_code": {
                        "type": "string",
                        "example": "AUTH_ERROR"
                    }
                }
            },
            "WebhookEvent": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "Same value as the ShipAPostcard-Event-Id header; stays the same across retries."
                    },
                    "type": {
                        "type": "string",
                        "enum": [
                            "postcard.created",
                            "postcard.sent_to_printer",
                            "postcard.delivered",
                            "postcard.failed",
                            "batch.payment_failed"
                        ]
                    },
                    "created_at": {
                        "type": "integer",
                        "description": "Unix timestamp."
                    },
                    "data": {
                        "type": "object"
                    }
                }
            }
        }
    }
}