# Draft an invoice; idempotent on the key. It has no number until it is finalised

`POST /invoices` · Rivier · shop

Draft an invoice; idempotent on the key. It has no number until it is finalised.

- Scope: shop:write
- Mcp: rivier_invoices_draft
- Graphql: Mutation.draftInvoice
- Sdk: shop.invoice.draft
- Cli: shop invoice draft

## Request body

`application/json`

```json
{
  "type": "object",
  "properties": {
    "seriesKey": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]{0,30}$"
    },
    "currency": {
      "type": "string",
      "pattern": "^[a-z]{3}$"
    },
    "contact": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "email": {
          "type": "string",
          "format": "email",
          "maxLength": 254
        },
        "addressLines": {
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 200
          },
          "maxItems": 6,
          "default": []
        },
        "country": {
          "type": "string",
          "pattern": "^[A-Z]{2}$"
        },
        "vatId": {
          "type": "string",
          "maxLength": 30
        },
        "registration": {
          "type": "string",
          "maxLength": 60
        },
        "city": {
          "type": "string",
          "maxLength": 100
        },
        "postalCode": {
          "type": "string",
          "maxLength": 20
        },
        "endpointScheme": {
          "type": "string",
          "pattern": "^[0-9A-Z]{4}$"
        },
        "endpointId": {
          "type": "string",
          "pattern": "^\\S(.{0,48}\\S)?$"
        },
        "paymentAccount": {
          "type": "string",
          "pattern": "^[A-Za-z0-9 ]{4,42}$"
        },
        "paymentBic": {
          "type": "string",
          "pattern": "^[A-Za-z0-9]{8,11}$"
        },
        "language": {
          "type": "string",
          "pattern": "^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$",
          "maxLength": 20
        }
      },
      "required": [
        "name"
      ],
      "additionalProperties": false
    },
    "delivery": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 200
        },
        "addressLines": {
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 200
          },
          "maxItems": 6,
          "default": []
        },
        "city": {
          "type": "string",
          "maxLength": 100
        },
        "postalCode": {
          "type": "string",
          "maxLength": 20
        },
        "country": {
          "type": "string",
          "pattern": "^[A-Z]{2}$"
        }
      },
      "additionalProperties": false
    },
    "lines": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "quantity": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 1000000,
            "default": 1
          },
          "unit": {
            "type": "string",
            "maxLength": 10,
            "default": "C62"
          },
          "unitAmountMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99999999999
          },
          "discountMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99999999999,
            "default": 0
          },
          "taxRateBp": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000
          },
          "taxCategory": {
            "type": "string",
            "enum": [
              "S",
              "Z",
              "E",
              "AE",
              "K",
              "G",
              "O",
              "L",
              "M"
            ],
            "default": "S"
          },
          "productId": {
            "type": "string",
            "format": "uuid"
          },
          "source": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "maxLength": 40
              },
              "id": {
                "type": "string",
                "maxLength": 120
              }
            },
            "required": [
              "kind",
              "id"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "description",
          "unitAmountMinor"
        ],
        "additionalProperties": false
      },
      "maxItems": 200,
      "default": []
    },
    "issueDate": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "dueDate": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "supplyDate": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "periodFrom": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "periodTo": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "reference": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "maxLength": 40
        },
        "id": {
          "type": "string",
          "maxLength": 120
        }
      },
      "required": [
        "kind",
        "id"
      ],
      "additionalProperties": false
    },
    "buyerReference": {
      "type": "string",
      "maxLength": 120,
      "default": ""
    },
    "purchaseOrder": {
      "type": "string",
      "maxLength": 120,
      "default": ""
    },
    "paymentTerms": {
      "type": "string",
      "maxLength": 500
    },
    "paymentInstructions": {
      "type": "string",
      "maxLength": 1000
    },
    "notes": {
      "type": "string",
      "maxLength": 2000,
      "default": ""
    },
    "reverseCharge": {
      "type": "boolean",
      "default": false
    },
    "roundingMinor": {
      "type": "integer",
      "minimum": -99,
      "maximum": 99,
      "default": 0
    },
    "idempotencyKey": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    }
  },
  "required": [
    "currency",
    "contact",
    "idempotencyKey"
  ],
  "additionalProperties": false
}
```

## Responses

- `201`: Success
- `400`: The request was malformed
- `401`: No valid credential
- `403`: The credential lacks the scope, origin or address
- `429`: Over the key's rate limit; see Retry-After

## Example

```sh
curl -X POST 'https://api.rivier.ai/invoices' \
  -H 'Authorization: Bearer $KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "currency": "string",
  "contact": {
    "name": "string"
  },
  "idempotencyKey": "string"
}'
```