Subscriptions

GET /v1/subscriptions

List subscriptions

Scope: subscriptions:read

Query
status	active | paused | cancelled
customerId	Filter by customer
nextInvoiceBefore	YYYY-MM-DD — next occurrence on/before this date
externalReference	Exact match on your own reference
limit	Page size, 1-200 (default 50)
cursor	Opaque cursor from meta.nextCursor

curl

curl https://app.rieck.nu/api/v1/subscriptions \
  -H "Authorization: Bearer $RIECK_API_KEY"

TypeScript

const svar = await rieck.request("GET", "/v1/subscriptions");

---

POST /v1/subscriptions

Create subscription

Scope: subscriptions:write

curl

curl -X POST https://app.rieck.nu/api/v1/subscriptions \
  -H "Authorization: Bearer $RIECK_API_KEY" \
  -H "Idempotency-Key: order-2041" \
  -d '{
    "customerId": "9b2f1c1e-…",
    "name": "Acme ApS",
    "interval": {
      "unit": "week",
      "count": 1
    },
    "startDate": "2026-08-15",
    "lines": [
      {
        "description": "Consulting",
        "quantity": 1,
        "unitPriceOere": 125000,
        "vatRateBps": 2500
      }
    ],
    "endDate": "2026-08-15",
    "dueDays": 14,
    "autoSend": true,
    "externalReference": "crm-9001"
  }'

TypeScript

const svar = await rieck.request("POST", "/v1/subscriptions", {
  body: {
    "customerId": "9b2f1c1e-…",
    "name": "Acme ApS",
    "interval": {
      "unit": "week",
      "count": 1
    },
    "startDate": "2026-08-15",
    "lines": [
      {
        "description": "Consulting",
        "quantity": 1,
        "unitPriceOere": 125000,
        "vatRateBps": 2500
      }
    ],
    "endDate": "2026-08-15",
    "dueDays": 14,
    "autoSend": true,
    "externalReference": "crm-9001"
  },
});

Request body — fuldt JSON Schema

{
  "type": "object",
  "properties": {
    "customerId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "interval": {
      "type": "object",
      "properties": {
        "unit": {
          "type": "string",
          "enum": [
            "week",
            "month",
            "year"
          ]
        },
        "count": {
          "type": "integer",
          "minimum": 1,
          "maximum": 24
        }
      },
      "required": [
        "unit",
        "count"
      ],
      "additionalProperties": false
    },
    "startDate": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "endDate": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        {
          "type": "null"
        }
      ]
    },
    "dueDays": {
      "default": 30,
      "type": "integer",
      "minimum": 0,
      "maximum": 365
    },
    "autoSend": {
      "default": true,
      "type": "boolean"
    },
    "lines": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "quantity": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 100000
          },
          "unitPriceOere": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100000000
          },
          "vatRateBps": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "vatExemptionReason": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "ML13",
                  "OMVENDT",
                  "EU_VARE",
                  "EKSPORT"
                ]
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "description",
          "quantity",
          "unitPriceOere"
        ],
        "additionalProperties": false
      }
    },
    "externalReference": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ]
    },
    "metadata": {
      "anyOf": [
        {
          "type": "object",
          "propertyNames": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40
          },
          "additionalProperties": {
            "type": "string",
            "maxLength": 500
          }
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "customerId",
    "name",
    "interval",
    "startDate",
    "lines"
  ],
  "additionalProperties": false
}

---

GET /v1/subscriptions/{subscriptionId}

Get subscription

Scope: subscriptions:read

curl

curl https://app.rieck.nu/api/v1/subscriptions/9b2f1c1e-… \
  -H "Authorization: Bearer $RIECK_API_KEY"

TypeScript

const svar = await rieck.request("GET", "/v1/subscriptions/9b2f1c1e-…");

---

PATCH /v1/subscriptions/{subscriptionId}

Update recipe

Partial; affects FUTURE occurrences only. status/nextInvoiceDate are never writable.

Scope: subscriptions:write

curl

curl -X PATCH https://app.rieck.nu/api/v1/subscriptions/9b2f1c1e-… \
  -H "Authorization: Bearer $RIECK_API_KEY" \
  -H "Idempotency-Key: order-2041" \
  -d '{
    "customerId": "9b2f1c1e-…",
    "name": "Acme ApS",
    "interval": {
      "unit": "week",
      "count": 1
    },
    "startDate": "2026-08-15"
  }'

TypeScript

const svar = await rieck.request("PATCH", "/v1/subscriptions/9b2f1c1e-…", {
  body: {
    "customerId": "9b2f1c1e-…",
    "name": "Acme ApS",
    "interval": {
      "unit": "week",
      "count": 1
    },
    "startDate": "2026-08-15"
  },
});

Request body — fuldt JSON Schema

{
  "type": "object",
  "properties": {
    "customerId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "interval": {
      "type": "object",
      "properties": {
        "unit": {
          "type": "string",
          "enum": [
            "week",
            "month",
            "year"
          ]
        },
        "count": {
          "type": "integer",
          "minimum": 1,
          "maximum": 24
        }
      },
      "required": [
        "unit",
        "count"
      ],
      "additionalProperties": false
    },
    "startDate": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "endDate": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        {
          "type": "null"
        }
      ]
    },
    "dueDays": {
      "default": 30,
      "type": "integer",
      "minimum": 0,
      "maximum": 365
    },
    "autoSend": {
      "default": true,
      "type": "boolean"
    },
    "lines": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "quantity": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 100000
          },
          "unitPriceOere": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100000000
          },
          "vatRateBps": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "vatExemptionReason": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "ML13",
                  "OMVENDT",
                  "EU_VARE",
                  "EKSPORT"
                ]
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "description",
          "quantity",
          "unitPriceOere"
        ],
        "additionalProperties": false
      }
    },
    "externalReference": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ]
    },
    "metadata": {
      "anyOf": [
        {
          "type": "object",
          "propertyNames": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40
          },
          "additionalProperties": {
            "type": "string",
            "maxLength": 500
          }
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "additionalProperties": false
}

---

POST /v1/subscriptions/{subscriptionId}/pause

Pause (from active)

Scope: subscriptions:write

curl

curl -X POST https://app.rieck.nu/api/v1/subscriptions/9b2f1c1e-…/pause \
  -H "Authorization: Bearer $RIECK_API_KEY" \
  -H "Idempotency-Key: order-2041"

TypeScript

const svar = await rieck.request("POST", "/v1/subscriptions/9b2f1c1e-…/pause");

---

POST /v1/subscriptions/{subscriptionId}/resume

Resume (from paused)

Scope: subscriptions:write

curl

curl -X POST https://app.rieck.nu/api/v1/subscriptions/9b2f1c1e-…/resume \
  -H "Authorization: Bearer $RIECK_API_KEY" \
  -H "Idempotency-Key: order-2041"

TypeScript

const svar = await rieck.request("POST", "/v1/subscriptions/9b2f1c1e-…/resume");

---

POST /v1/subscriptions/{subscriptionId}/cancel

Cancel (final)

Scope: subscriptions:write

curl

curl -X POST https://app.rieck.nu/api/v1/subscriptions/9b2f1c1e-…/cancel \
  -H "Authorization: Bearer $RIECK_API_KEY" \
  -H "Idempotency-Key: order-2041"

TypeScript

const svar = await rieck.request("POST", "/v1/subscriptions/9b2f1c1e-…/cancel");

---

GET /v1/subscriptions/{subscriptionId}/invoices

Generated invoices

Scope: subscriptions:read

curl

curl https://app.rieck.nu/api/v1/subscriptions/9b2f1c1e-…/invoices \
  -H "Authorization: Bearer $RIECK_API_KEY"

TypeScript

const svar = await rieck.request("GET", "/v1/subscriptions/9b2f1c1e-…/invoices");

---

GET /v1/subscriptions/{subscriptionId}/next_invoice

Preview next occurrence

Scope: subscriptions:read

curl

curl https://app.rieck.nu/api/v1/subscriptions/9b2f1c1e-…/next_invoice \
  -H "Authorization: Bearer $RIECK_API_KEY"

TypeScript

const svar = await rieck.request("GET", "/v1/subscriptions/9b2f1c1e-…/next_invoice");

---

POST /v1/subscriptions/{subscriptionId}/run

Run next due period now

Respects the engine’s lease and run receipt — one invoice per period; a future period cannot run early.

Scope: subscriptions:write

curl

curl -X POST https://app.rieck.nu/api/v1/subscriptions/9b2f1c1e-…/run \
  -H "Authorization: Bearer $RIECK_API_KEY" \
  -H "Idempotency-Key: order-2041"

TypeScript

const svar = await rieck.request("POST", "/v1/subscriptions/9b2f1c1e-…/run");