API Documentation

Authentication

All API requests require authentication using an API key. Include your API key in theAuthorization header:

Authorization: Bearer pl_live_xxxxxxxxxxxxx

Generate API keys in your Settings.

Rate Limits

API requests are rate limited per API key. Limits vary by endpoint:

Daily limits: 500 orders per day, 5,000 total API calls per day.

Rate limit information is included in response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1703203200
X-RateLimit-Daily-Limit: 5000
X-RateLimit-Daily-Remaining: 4987
X-RateLimit-Daily-Reset: 1703289600

Errors

The API uses conventional HTTP response codes. Errors include a JSON body with details:

{
  "error": "invalid_api_key",
  "message": "Invalid or inactive API key",
  "suggestion": "Check that your API key is correct and active."
}

Create Order

Create a new order for written letters.

Request Body

{
  "message": "Dear {{first_name}},\n\nThank you for your business...",
  "recipients": [
    {
      "first_name": "John",
      "last_name": "Doe",
      "address_line1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zip": "10001"
    }
  ],
  "options": {
    "handwriting_style": "elegant",
    "paper_type": "cream",
    "product_type": "letter"
  },
  "payment": {
    "method": "card_on_file"
  }
}

Parameters

Response

{
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "paid",
  "letter_count": 1,
  "total_cents": 499,
  "tracking_url": "https://premierletters.com/orders/550e8400..."
}

A card-on-file order is answered 201 once the card is charged, even if marking the order paid hits a transient error on our side. The body then reports status: "pending_payment" and the order moves to paid on its own. Do not resubmit: the card has already been charged.

Orders under 5 pieces carry a per-piece small-order handling fee (see small_order_handling in GET /config). It is included in total_cents and waived for balance payments.

402: card on file could not be charged

The order is created anyway, awaiting payment. Send the customer to checkout_url (it pays exactly this order). Do not resubmit the request.

{
  "error": "payment_failed",
  "message": "Payment failed: requires_action",
  "suggestion": "Try a different payment method, or complete payment for this order at checkout_url.",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "checkout_url": "https://checkout.stripe.com/pay/cs_live_..."
}

402: insufficient balance

With payment.method: "balance", when the prepaid balance does not cover the order nothing is charged and no order is kept. If the balance payment fails for another reason the response is a 500 balance_payment_failed: the order is not placed, and if your balance changed it is corrected automatically.

{
  "error": "insufficient_balance",
  "message": "Your prepaid balance does not cover this order.",
  "suggestion": "Top up at https://www.premierletters.com/settings/billing",
  "balance_cents": 300,
  "shortfall_cents": 254
}

Get Order

Retrieve details of a specific order including recipient status and tracking.

Response

{
  "order": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "mailed",
    "letter_count": 1,
    "total_cents": 499,
    "shipped_date": "2024-01-15T10:30:00Z"
  },
  "recipients": [
    {
      "id": "rec_123",
      "name": "John Doe",
      "status": "mailed",
      "tracking_number": "9400111899223..."
    }
  ],
  "summary": {
    "total": 1,
    "pending": 0,
    "mailed": 1
  }
}

Validate Order

Validate an order without creating it. Useful for testing integrations and getting pricing.

Request body is the same as Create Order. Response includes validation status and pricing:

{
  "valid": true,
  "letter_count": 10,
  "total_cents": 4990,
  "total_formatted": "$49.90",
  "message": "Order is valid. 10 letters at $4.99 each = $49.90 total."
}

Webhook Events

Receive real-time notifications when order status changes.

Webhook Payload

{
  "event": "order.shipped",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "order_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "mailed",
    "letter_preview": "Dear John,\n\nThank you for your business...",
    "recipient_count": 10,
    "total": 34.90,
    "tracking_numbers": ["9400111899223..."],
    "source": "api"
  }
}

Manage Webhook Endpoints

List Endpoints

Create Endpoint

{
  "url": "https://your-app.com/webhooks/premier-letters",
  "events": ["order.paid", "order.shipped"]
}

Response includes a signing secret - store it securely, it's only shown once.

Update Endpoint

Delete Endpoint

Signature Verification

All webhooks include a signature header for verification. Always verify signatures in production.

Headers

Verification Example (Node.js)

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler:
app.post('/webhooks/premier-letters', (req, res) => {
  const signature = req.headers['x-premier-letters-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifyWebhookSignature(payload, signature, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process webhook...
  res.status(200).json({ received: true });
});