> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paperjoy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Draft postcards: prepare, review, and send later

> Save free drafts, edit and preview them, then submit when ready. Credits are used at submit.

A draft is a postcard that hasn't been ordered yet. It's free, it's never written or mailed, and you can change it as often as you like. When it's ready, submit it: Paperjoy then checks it, uses one credit, and the postcard continues as a normal order.

```mermaid theme={null}
flowchart LR
  D["draft"] -->|"submit (1 credit)"| new
  D -->|delete| X["deleted"]
  new --> queued
```

## Create a draft

Send `"draft": true` to [`POST /api/postcards`](https://docs.paperjoy.co/en/postcards/create). Every field is optional, so you can save a draft before you know the address or the final text.

```bash theme={null}
curl https://paperjoy.co/api/postcards \
  --header "Authorization: Bearer $PAPERJOY_API_KEY" \
  --header "Idempotency-Key: draft-order-1042" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "draft": true,
    "recipient": { "first_name": "Anna", "last_name": "Kowalska" },
    "content": "Dear Anna,\nthank you for your first order!",
    "font_id": "font-1"
  }'
```

The response is `201 Created` with `"status": "draft"` and `"submitted_at": null`. Creating a draft:

* uses no credit and doesn't need a credit balance;
* doesn't count toward the daily limit of 100 postcards;
* checks each field you send (length, postal code format, font), but not whether the text fits on the card or the address fits on the envelope. Those checks run when you submit.

You can have up to **100 open drafts** per account in each mode. Beyond that, creating a draft returns `422` with an error on `draft`. Submit or delete some drafts first.

Without `draft`, or with `"draft": false`, `POST /api/postcards` orders the postcard right away, as before.

## Edit a draft

`PATCH /api/postcards/{id}` changes only the fields you send. Send `null` to clear a field. `address` and `recipient` are replaced as a whole, so send all their parts.

```bash theme={null}
curl --request PATCH https://paperjoy.co/api/postcards/pc_MXP7a4Ni0c \
  --header "Authorization: Bearer $PAPERJOY_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "address": {
      "line_1": "ul. Marszałkowska 10",
      "postal_code": "00-001",
      "city": "Warszawa",
      "country": "PL"
    }
  }'
```

| Response | When |
| - | - |
| `200 OK` | The draft was updated. |
| `409 Conflict` | The postcard was already submitted. Only drafts can be changed. |
| `422` | A field is invalid, or you sent a field a postcard doesn't have, such as `status`. |

You can't set `status` yourself. A draft becomes an order only when you submit it.

To check how the draft looks, use [`POST /api/postcards/preview`](https://docs.paperjoy.co/en/postcards/preview) with the same `content`, `signature`, and `font_id`.

## Submit a draft

`POST /api/postcards/{id}/submit` orders the draft. It needs no body, but it does need an `Idempotency-Key`.

```bash theme={null}
curl --request POST https://paperjoy.co/api/postcards/pc_MXP7a4Ni0c/submit \
  --header "Authorization: Bearer $PAPERJOY_API_KEY" \
  --header "Idempotency-Key: submit-order-1042" \
  --header "Accept: application/json"
```

Paperjoy validates the draft exactly like a new postcard, including card and envelope fit. If it passes, it uses one credit (live only), sets `"status": "new"` and `submitted_at`, and starts the content check.

| Response | When |
| - | - |
| `200 OK` | The postcard was ordered. A retry with the same key returns this response again, with an `Idempotency-Relayed` header, and charges nothing. |
| `402 Payment Required` | Live mode and less than one credit. The postcard stays a draft. |
| `409 Conflict` | The postcard was already submitted, or the key was used before for a different request. |
| `422` | The draft is incomplete or doesn't fit. `errors` lists the fields to fix. The postcard stays a draft. |
| `429` | The daily limit of 100 postcards was reached. |

A draft is never charged twice. After a `402` or `422`, fix the cause and submit again with the same key.

## Delete a draft

```bash theme={null}
curl --request DELETE https://paperjoy.co/api/postcards/pc_MXP7a4Ni0c \
  --header "Authorization: Bearer $PAPERJOY_API_KEY" \
  --header "Accept: application/json"
```

`204 No Content` when the draft is gone. Deleting is permanent. Submitted postcards can't be deleted and return `409`.

## Find your drafts

`GET /api/postcards?status=draft` lists only drafts. See [Track postcards](https://docs.paperjoy.co/en/postcards/list-and-retrieve.md#list-postcards).

## Unused drafts are deleted after 30 days

Paperjoy permanently deletes drafts that haven't changed for **30 days**. Editing a draft resets the clock. Submitted postcards are never deleted this way.

## In the Paperjoy app

In the editor, **Zapisz szkic** (Save draft) saves the card as a draft without using a credit. The dashboard has a **Szkice** (Drafts) tab: open a draft to edit it, then click **Wyślij (1 kredyt)** (Send, 1 credit) or **Usuń szkic** (Delete draft).

Drafts created by your AI assistant through the [MCP server](https://docs.paperjoy.co/en/integrations/mcp.md) appear in the same tab, so you can review them before anything is sent.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.