Subscriptions

GET `/v1/subscriptions`

List subscriptions

subscriptions:read

Parameter	In	Type	Required	Description
`status`	query	`string`	No	active \| paused \| cancelled
`customerId`	query	`string`	No	Filter by customer
`nextInvoiceBefore`	query	`string`	No	YYYY-MM-DD — next occurrence on/before this date
`externalReference`	query	`string`	No	Exact match on your own reference
`limit`	query	`integer`	No	Page size, 1-200 (default 50)
`cursor`	query	`string`	No	Opaque cursor from meta.nextCursor

Request exampleNo request body

curl https://api.rieckflow.com/v1/subscriptions \
  -H "Authorization: Bearer $RIECK_API_KEY"

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

{
  "data": [
    {
      "id": "9b2f1c1e-6b87-4d9b-91a0-47c8d72b8440",
      "customerId": "467a0d8d-b9b2-4df3-bf7b-17d649442890",
      "customerName": "Acme ApS",
      "name": "Monthly service",
      "interval": {
        "unit": "month",
        "count": 1
      },
      "startDate": "2026-08-01",
      "endDate": null,
      "nextInvoiceDate": "2026-09-01",
      "dueDays": 14,
      "autoSend": true,
      "status": "active",
      "lines": [
        {
          "description": "Monthly service",
          "quantity": 1,
          "unitPriceOere": 125000,
          "vatRateBps": 2500
        }
      ],
      "invoiceCount": 1,
      "periodsBehind": 0,
      "latestInvoice": {
        "invoiceId": "5c0d10ec-f086-48c6-b1c7-b389a47ac6d1",
        "invoiceNumber": 1042,
        "periodDate": "2026-08-01"
      },
      "externalReference": "subscription-88",
      "metadata": null,
      "createdAt": "2026-08-01T08:00:00Z"
    }
  ],
  "meta": {
    "nextCursor": null
  }
}

200 Success envelopeapplication/json

Response fields 6

Field	Type	Description
`data[].id`	`uuid`	Stable subscription id.
`data[].interval`	`object`	Billing cadence unit and count.
`data[].nextInvoiceDate`	`date`	Next period the engine will invoice.
`data[].status`	`active \| paused \| cancelled`	Current subscription state.
`data[].periodsBehind`	`integer`	Unprocessed periods. Zero means on schedule.
`meta.nextCursor`	`string	null`

Possible errors 5

HTTP	Code	Meaning
400	`invalid_cursor`	The cursor is malformed, expired or belongs to another list shape.
401	`invalid_api_key`	The API key is missing, invalid, expired or revoked.
403	`api_not_included`	The organisation’s plan does not include API access.
403	`insufficient_scope`	The key does not have the required scope.
429	`rate_limited`	The organisation’s rate budget is exhausted.

POST `/v1/subscriptions`

Create subscription

subscriptions:write

Request body fields 21

Field	Type	Required	Description
`customerId`	`string`	Yes	The customer this resource belongs to.
`name`	`string`	Yes	Human-readable name.
`interval`	`object`	Yes	Field in the request payload.
`interval.unit`	`string`	Yes	Field in the request payload.
`interval.count`	`integer`	Yes	Field in the request payload.
`startDate`	`string`	Yes	Field in the request payload.
`endDate`	`string`	No	Field in the request payload.
`periodCount`	`integer`	No	Field in the request payload.
`trialEnd`	`string`	No	Field in the request payload.
`trialEndBehavior`	`string`	No	Field in the request payload.
`dueDays`	`integer`	No	Field in the request payload.
`autoSend`	`boolean`	No	Field in the request payload.
`pauseFeeOere`	`integer`	No	Field in the request payload.
`lines`	`object[]`	Yes	Invoice or subscription line items.
`lines[].description`	`string`	Yes	Human-readable description.
`lines[].quantity`	`number`	Yes	Positive quantity for this line.
`lines[].unitPriceOere`	`integer`	Yes	Unit price in integer øre.
`lines[].vatRateBps`	`integer`	No	VAT rate in basis points. 2500 means 25%.
`lines[].vatExemptionReason`	`string`	No	Required legal reason when the VAT rate is zero.
`externalReference`	`string`	No	Your stable reference for reconciliation and idempotent imports.
`metadata`	`object`	No	Your own string key/value data. Never used for Rieck business logic.

Request exampleapplication/json

curl -X POST https://api.rieckflow.com/v1/subscriptions \
  -H "Authorization: Bearer $RIECK_API_KEY" \
  -H "Idempotency-Key: order-2041" \
  -H "Content-Type: application/json" \
  -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"
  }'

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"
  },
});

{
  "data": {
    "id": "9b2f1c1e-6b87-4d9b-91a0-47c8d72b8440",
    "customerId": "467a0d8d-b9b2-4df3-bf7b-17d649442890",
    "customerName": "Acme ApS",
    "name": "Monthly service",
    "interval": {
      "unit": "month",
      "count": 1
    },
    "startDate": "2026-08-01",
    "endDate": null,
    "nextInvoiceDate": "2026-09-01",
    "dueDays": 14,
    "autoSend": true,
    "status": "active",
    "lines": [
      {
        "description": "Monthly service",
        "quantity": 1,
        "unitPriceOere": 125000,
        "vatRateBps": 2500
      }
    ],
    "invoiceCount": 1,
    "periodsBehind": 0,
    "latestInvoice": {
      "invoiceId": "5c0d10ec-f086-48c6-b1c7-b389a47ac6d1",
      "invoiceNumber": 1042,
      "periodDate": "2026-08-01"
    },
    "externalReference": "subscription-88",
    "metadata": null,
    "createdAt": "2026-08-01T08:00:00Z"
  }
}

201 Success envelopeapplication/json

Response fields 5

Field	Type	Description
`data.id`	`uuid`	Stable subscription id.
`data.interval`	`object`	Billing cadence unit and count.
`data.nextInvoiceDate`	`date`	Next period the engine will invoice.
`data.status`	`active \| paused \| cancelled`	Current subscription state.
`data.periodsBehind`	`integer`	Unprocessed periods. Zero means on schedule.

Possible errors 9

HTTP	Code	Meaning
400	`invalid_idempotency_key`	Idempotency-Key is missing or malformed.
400	`invalid_request`	The request body or parameter failed validation.
401	`invalid_api_key`	The API key is missing, invalid, expired or revoked.
403	`api_not_included`	The organisation’s plan does not include API access.
403	`insufficient_scope`	The key does not have the required scope.
409	`idempotency_conflict`	The same key was used with a different request.
409	`idempotency_in_progress`	The same operation is currently being processed. Retry later.
413	`payload_too_large`	The JSON or uploaded file exceeds this endpoint’s size limit.
429	`rate_limited`	The organisation’s rate budget is exhausted.

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"
        }
      ]
    },
    "periodCount": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 1,
          "maximum": 600
        },
        {
          "type": "null"
        }
      ]
    },
    "trialEnd": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        {
          "type": "null"
        }
      ]
    },
    "trialEndBehavior": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "cancel",
            "create_invoice",
            "pause"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "dueDays": {
      "default": 30,
      "type": "integer",
      "minimum": 0,
      "maximum": 365
    },
    "autoSend": {
      "default": true,
      "type": "boolean"
    },
    "pauseFeeOere": {
      "default": 0,
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000000
    },
    "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

subscriptions:read

Parameter	In	Type	Required	Description
`subscriptionId`	path	`string`	Yes

Request exampleNo request body

curl https://api.rieckflow.com/v1/subscriptions/9b2f1c1e-… \
  -H "Authorization: Bearer $RIECK_API_KEY"

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

{
  "data": {
    "id": "9b2f1c1e-6b87-4d9b-91a0-47c8d72b8440",
    "customerId": "467a0d8d-b9b2-4df3-bf7b-17d649442890",
    "customerName": "Acme ApS",
    "name": "Monthly service",
    "interval": {
      "unit": "month",
      "count": 1
    },
    "startDate": "2026-08-01",
    "endDate": null,
    "nextInvoiceDate": "2026-09-01",
    "dueDays": 14,
    "autoSend": true,
    "status": "active",
    "lines": [
      {
        "description": "Monthly service",
        "quantity": 1,
        "unitPriceOere": 125000,
        "vatRateBps": 2500
      }
    ],
    "invoiceCount": 1,
    "periodsBehind": 0,
    "latestInvoice": {
      "invoiceId": "5c0d10ec-f086-48c6-b1c7-b389a47ac6d1",
      "invoiceNumber": 1042,
      "periodDate": "2026-08-01"
    },
    "externalReference": "subscription-88",
    "metadata": null,
    "createdAt": "2026-08-01T08:00:00Z"
  }
}

200 Success envelopeapplication/json

Response fields 5

Field	Type	Description
`data.id`	`uuid`	Stable subscription id.
`data.interval`	`object`	Billing cadence unit and count.
`data.nextInvoiceDate`	`date`	Next period the engine will invoice.
`data.status`	`active \| paused \| cancelled`	Current subscription state.
`data.periodsBehind`	`integer`	Unprocessed periods. Zero means on schedule.

Possible errors 5

HTTP	Code	Meaning
401	`invalid_api_key`	The API key is missing, invalid, expired or revoked.
403	`api_not_included`	The organisation’s plan does not include API access.
403	`insufficient_scope`	The key does not have the required scope.
404	`subscription_not_found`	The subscription does not exist or belongs to another organisation.
429	`rate_limited`	The organisation’s rate budget is exhausted.

PATCH `/v1/subscriptions/{subscriptionId}`

Update recipe

subscriptions:write

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

Parameter	In	Type	Required	Description
`subscriptionId`	path	`string`	Yes

Request body fields 21

Field	Type	Required	Description
`customerId`	`string`	No	The customer this resource belongs to.
`name`	`string`	No	Human-readable name.
`interval`	`object`	No	Field in the request payload.
`interval.unit`	`string`	Yes	Field in the request payload.
`interval.count`	`integer`	Yes	Field in the request payload.
`startDate`	`string`	No	Field in the request payload.
`endDate`	`string`	No	Field in the request payload.
`periodCount`	`integer`	No	Field in the request payload.
`trialEnd`	`string`	No	Field in the request payload.
`trialEndBehavior`	`string`	No	Field in the request payload.
`dueDays`	`integer`	No	Field in the request payload.
`autoSend`	`boolean`	No	Field in the request payload.
`pauseFeeOere`	`integer`	No	Field in the request payload.
`lines`	`object[]`	No	Invoice or subscription line items.
`lines[].description`	`string`	Yes	Human-readable description.
`lines[].quantity`	`number`	Yes	Positive quantity for this line.
`lines[].unitPriceOere`	`integer`	Yes	Unit price in integer øre.
`lines[].vatRateBps`	`integer`	No	VAT rate in basis points. 2500 means 25%.
`lines[].vatExemptionReason`	`string`	No	Required legal reason when the VAT rate is zero.
`externalReference`	`string`	No	Your stable reference for reconciliation and idempotent imports.
`metadata`	`object`	No	Your own string key/value data. Never used for Rieck business logic.

Request exampleapplication/json

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

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

{
  "data": {
    "id": "9b2f1c1e-6b87-4d9b-91a0-47c8d72b8440",
    "customerId": "467a0d8d-b9b2-4df3-bf7b-17d649442890",
    "customerName": "Acme ApS",
    "name": "Monthly service",
    "interval": {
      "unit": "month",
      "count": 1
    },
    "startDate": "2026-08-01",
    "endDate": null,
    "nextInvoiceDate": "2026-09-01",
    "dueDays": 14,
    "autoSend": true,
    "status": "active",
    "lines": [
      {
        "description": "Monthly service",
        "quantity": 1,
        "unitPriceOere": 125000,
        "vatRateBps": 2500
      }
    ],
    "invoiceCount": 1,
    "periodsBehind": 0,
    "latestInvoice": {
      "invoiceId": "5c0d10ec-f086-48c6-b1c7-b389a47ac6d1",
      "invoiceNumber": 1042,
      "periodDate": "2026-08-01"
    },
    "externalReference": "subscription-88",
    "metadata": null,
    "createdAt": "2026-08-01T08:00:00Z"
  }
}

200 Success envelopeapplication/json

Response fields 5

Field	Type	Description
`data.id`	`uuid`	Stable subscription id.
`data.interval`	`object`	Billing cadence unit and count.
`data.nextInvoiceDate`	`date`	Next period the engine will invoice.
`data.status`	`active \| paused \| cancelled`	Current subscription state.
`data.periodsBehind`	`integer`	Unprocessed periods. Zero means on schedule.

Possible errors 10

HTTP	Code	Meaning
400	`invalid_idempotency_key`	Idempotency-Key is missing or malformed.
400	`invalid_request`	The request body or parameter failed validation.
401	`invalid_api_key`	The API key is missing, invalid, expired or revoked.
403	`api_not_included`	The organisation’s plan does not include API access.
403	`insufficient_scope`	The key does not have the required scope.
404	`subscription_not_found`	The subscription does not exist or belongs to another organisation.
409	`idempotency_conflict`	The same key was used with a different request.
409	`idempotency_in_progress`	The same operation is currently being processed. Retry later.
413	`payload_too_large`	The JSON or uploaded file exceeds this endpoint’s size limit.
429	`rate_limited`	The organisation’s rate budget is exhausted.

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"
        }
      ]
    },
    "periodCount": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 1,
          "maximum": 600
        },
        {
          "type": "null"
        }
      ]
    },
    "trialEnd": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        {
          "type": "null"
        }
      ]
    },
    "trialEndBehavior": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "cancel",
            "create_invoice",
            "pause"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "dueDays": {
      "type": "integer",
      "minimum": 0,
      "maximum": 365
    },
    "autoSend": {
      "type": "boolean"
    },
    "pauseFeeOere": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000000
    },
    "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)

subscriptions:write

Parameter	In	Type	Required	Description
`subscriptionId`	path	`string`	Yes

Request exampleNo request body

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

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

{
  "data": {
    "id": "9b2f1c1e-6b87-4d9b-91a0-47c8d72b8440",
    "customerId": "467a0d8d-b9b2-4df3-bf7b-17d649442890",
    "customerName": "Acme ApS",
    "name": "Monthly service",
    "interval": {
      "unit": "month",
      "count": 1
    },
    "startDate": "2026-08-01",
    "endDate": null,
    "nextInvoiceDate": "2026-09-01",
    "dueDays": 14,
    "autoSend": true,
    "status": "active",
    "lines": [
      {
        "description": "Monthly service",
        "quantity": 1,
        "unitPriceOere": 125000,
        "vatRateBps": 2500
      }
    ],
    "invoiceCount": 1,
    "periodsBehind": 0,
    "latestInvoice": {
      "invoiceId": "5c0d10ec-f086-48c6-b1c7-b389a47ac6d1",
      "invoiceNumber": 1042,
      "periodDate": "2026-08-01"
    },
    "externalReference": "subscription-88",
    "metadata": null,
    "createdAt": "2026-08-01T08:00:00Z"
  }
}

200 Success envelopeapplication/json

Response fields 5

Field	Type	Description
`data.id`	`uuid`	Stable subscription id.
`data.interval`	`object`	Billing cadence unit and count.
`data.nextInvoiceDate`	`date`	Next period the engine will invoice.
`data.status`	`active \| paused \| cancelled`	Current subscription state.
`data.periodsBehind`	`integer`	Unprocessed periods. Zero means on schedule.

Possible errors 8

HTTP	Code	Meaning
400	`invalid_idempotency_key`	Idempotency-Key is missing or malformed.
401	`invalid_api_key`	The API key is missing, invalid, expired or revoked.
403	`api_not_included`	The organisation’s plan does not include API access.
403	`insufficient_scope`	The key does not have the required scope.
404	`subscription_not_found`	The subscription does not exist or belongs to another organisation.
409	`idempotency_conflict`	The same key was used with a different request.
409	`idempotency_in_progress`	The same operation is currently being processed. Retry later.
429	`rate_limited`	The organisation’s rate budget is exhausted.

POST `/v1/subscriptions/{subscriptionId}/resume`

Resume (from paused) — optional billingCycleAnchor: “unchanged” (default, keeps the cycle) or “now” (resets the cycle and invoices today, no proration)

subscriptions:write

Parameter	In	Type	Required	Description
`subscriptionId`	path	`string`	Yes

Request body fields 1

Field	Type	Required	Description
`billingCycleAnchor`	`string`	No	Field in the request payload.

Request exampleapplication/json

curl -X POST https://api.rieckflow.com/v1/subscriptions/9b2f1c1e-…/resume \
  -H "Authorization: Bearer $RIECK_API_KEY" \
  -H "Idempotency-Key: order-2041" \
  -H "Content-Type: application/json" \
  -d '{
    "billingCycleAnchor": "now"
  }'

const svar = await rieck.request("POST", "/v1/subscriptions/9b2f1c1e-…/resume", {
  body: {
    "billingCycleAnchor": "now"
  },
});

{
  "data": {
    "id": "9b2f1c1e-6b87-4d9b-91a0-47c8d72b8440",
    "customerId": "467a0d8d-b9b2-4df3-bf7b-17d649442890",
    "customerName": "Acme ApS",
    "name": "Monthly service",
    "interval": {
      "unit": "month",
      "count": 1
    },
    "startDate": "2026-08-01",
    "endDate": null,
    "nextInvoiceDate": "2026-09-01",
    "dueDays": 14,
    "autoSend": true,
    "status": "active",
    "lines": [
      {
        "description": "Monthly service",
        "quantity": 1,
        "unitPriceOere": 125000,
        "vatRateBps": 2500
      }
    ],
    "invoiceCount": 1,
    "periodsBehind": 0,
    "latestInvoice": {
      "invoiceId": "5c0d10ec-f086-48c6-b1c7-b389a47ac6d1",
      "invoiceNumber": 1042,
      "periodDate": "2026-08-01"
    },
    "externalReference": "subscription-88",
    "metadata": null,
    "createdAt": "2026-08-01T08:00:00Z"
  }
}

200 Success envelopeapplication/json

Response fields 5

Field	Type	Description
`data.id`	`uuid`	Stable subscription id.
`data.interval`	`object`	Billing cadence unit and count.
`data.nextInvoiceDate`	`date`	Next period the engine will invoice.
`data.status`	`active \| paused \| cancelled`	Current subscription state.
`data.periodsBehind`	`integer`	Unprocessed periods. Zero means on schedule.

Possible errors 10

HTTP	Code	Meaning
400	`invalid_idempotency_key`	Idempotency-Key is missing or malformed.
400	`invalid_request`	The request body or parameter failed validation.
401	`invalid_api_key`	The API key is missing, invalid, expired or revoked.
403	`api_not_included`	The organisation’s plan does not include API access.
403	`insufficient_scope`	The key does not have the required scope.
404	`subscription_not_found`	The subscription does not exist or belongs to another organisation.
409	`idempotency_conflict`	The same key was used with a different request.
409	`idempotency_in_progress`	The same operation is currently being processed. Retry later.
413	`payload_too_large`	The JSON or uploaded file exceeds this endpoint’s size limit.
429	`rate_limited`	The organisation’s rate budget is exhausted.

Request body — fuldt JSON Schema

{
  "type": "object",
  "properties": {
    "billingCycleAnchor": {
      "type": "string",
      "enum": [
        "now",
        "unchanged"
      ]
    }
  },
  "additionalProperties": false
}

POST `/v1/subscriptions/{subscriptionId}/cancel`

Cancel (final)

subscriptions:write

Parameter	In	Type	Required	Description
`subscriptionId`	path	`string`	Yes

Request exampleNo request body

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

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

{
  "data": {
    "id": "9b2f1c1e-6b87-4d9b-91a0-47c8d72b8440",
    "customerId": "467a0d8d-b9b2-4df3-bf7b-17d649442890",
    "customerName": "Acme ApS",
    "name": "Monthly service",
    "interval": {
      "unit": "month",
      "count": 1
    },
    "startDate": "2026-08-01",
    "endDate": null,
    "nextInvoiceDate": "2026-09-01",
    "dueDays": 14,
    "autoSend": true,
    "status": "active",
    "lines": [
      {
        "description": "Monthly service",
        "quantity": 1,
        "unitPriceOere": 125000,
        "vatRateBps": 2500
      }
    ],
    "invoiceCount": 1,
    "periodsBehind": 0,
    "latestInvoice": {
      "invoiceId": "5c0d10ec-f086-48c6-b1c7-b389a47ac6d1",
      "invoiceNumber": 1042,
      "periodDate": "2026-08-01"
    },
    "externalReference": "subscription-88",
    "metadata": null,
    "createdAt": "2026-08-01T08:00:00Z"
  }
}

200 Success envelopeapplication/json

Response fields 5

Field	Type	Description
`data.id`	`uuid`	Stable subscription id.
`data.interval`	`object`	Billing cadence unit and count.
`data.nextInvoiceDate`	`date`	Next period the engine will invoice.
`data.status`	`active \| paused \| cancelled`	Current subscription state.
`data.periodsBehind`	`integer`	Unprocessed periods. Zero means on schedule.

Possible errors 8

HTTP	Code	Meaning
400	`invalid_idempotency_key`	Idempotency-Key is missing or malformed.
401	`invalid_api_key`	The API key is missing, invalid, expired or revoked.
403	`api_not_included`	The organisation’s plan does not include API access.
403	`insufficient_scope`	The key does not have the required scope.
404	`subscription_not_found`	The subscription does not exist or belongs to another organisation.
409	`idempotency_conflict`	The same key was used with a different request.
409	`idempotency_in_progress`	The same operation is currently being processed. Retry later.
429	`rate_limited`	The organisation’s rate budget is exhausted.

GET `/v1/subscriptions/{subscriptionId}/invoices`

Generated invoices

subscriptions:read

Parameter	In	Type	Required	Description
`subscriptionId`	path	`string`	Yes

Request exampleNo request body

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

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

{
  "data": [
    {
      "periodDate": "2026-08-01",
      "invoiceId": "5c0d10ec-f086-48c6-b1c7-b389a47ac6d1",
      "invoiceNumber": 1042,
      "status": "issued",
      "issuedDate": "2026-08-01",
      "totalOere": 156250,
      "balanceOere": 156250
    }
  ]
}

200 Success envelopeapplication/json

Possible errors 5

HTTP	Code	Meaning
401	`invalid_api_key`	The API key is missing, invalid, expired or revoked.
403	`api_not_included`	The organisation’s plan does not include API access.
403	`insufficient_scope`	The key does not have the required scope.
404	`subscription_not_found`	The subscription does not exist or belongs to another organisation.
429	`rate_limited`	The organisation’s rate budget is exhausted.

GET `/v1/subscriptions/{subscriptionId}/next_invoice`

Preview next occurrence

subscriptions:read

Parameter	In	Type	Required	Description
`subscriptionId`	path	`string`	Yes

Request exampleNo request body

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

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

{
  "data": {
    "periodDate": "2026-09-01",
    "dueDate": "2026-09-15",
    "lines": [
      {
        "description": "Monthly service",
        "quantity": 1,
        "unitPriceOere": 125000,
        "vatRateBps": 2500,
        "netOere": 125000,
        "vatOere": 31250
      }
    ],
    "subtotalOere": 125000,
    "vatOere": 31250,
    "totalOere": 156250
  }
}

200 Date, lines, VAT and total — nothing is issued. data is null when nothing is coming.application/json

Response fields 4

Field	Type	Description
`data.periodDate`	`date`	Period the preview covers.
`data.dueDate`	`date`	Calculated due date.
`data.lines`	`object[]`	Calculated lines; nothing has been issued yet.
`data.totalOere`	`integer`	Preview total including VAT.

Possible errors 5

HTTP	Code	Meaning
401	`invalid_api_key`	The API key is missing, invalid, expired or revoked.
403	`api_not_included`	The organisation’s plan does not include API access.
403	`insufficient_scope`	The key does not have the required scope.
404	`subscription_not_found`	The subscription does not exist or belongs to another organisation.
429	`rate_limited`	The organisation’s rate budget is exhausted.

POST `/v1/subscriptions/{subscriptionId}/run`

Run next due period now

subscriptions:write

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

Parameter	In	Type	Required	Description
`subscriptionId`	path	`string`	Yes

Request exampleNo request body

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

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

{
  "data": {
    "outcome": "issued",
    "invoiceId": "5c0d10ec-f086-48c6-b1c7-b389a47ac6d1",
    "invoiceNumber": 1042,
    "sent": true
  }
}

200 Success envelopeapplication/json

Possible errors 8

HTTP	Code	Meaning
400	`invalid_idempotency_key`	Idempotency-Key is missing or malformed.
401	`invalid_api_key`	The API key is missing, invalid, expired or revoked.
403	`api_not_included`	The organisation’s plan does not include API access.
403	`insufficient_scope`	The key does not have the required scope.
404	`subscription_not_found`	The subscription does not exist or belongs to another organisation.
409	`idempotency_conflict`	The same key was used with a different request.
409	`idempotency_in_progress`	The same operation is currently being processed. Retry later.
429	`rate_limited`	The organisation’s rate budget is exhausted.

POST `/v1/subscriptions/{subscriptionId}/usage`

Report usage

subscriptions:write

The next occurrence invoices the period’s usage ON TOP of the template lines, aggregated per (unit, unit price). Send an idempotencyKey: a repeat returns the FIRST row id with duplicate:true and status 200 — not a 409, because after a timeout you cannot tell ‘already sent’ from ‘failed’. period is your own bookkeeping and does NOT decide when it is invoiced.

Parameter	In	Type	Required	Description
`subscriptionId`	path	`string`	Yes

Request body fields 6

Field	Type	Required	Description
`unit`	`string`	Yes	Field in the request payload.
`quantity`	`number`	Yes	Positive quantity for this line.
`unitPriceOere`	`integer`	Yes	Unit price in integer øre.
`idempotencyKey`	`string`	No	Field in the request payload.
`period`	`string`	No	Field in the request payload.
`metadata`	`object`	No	Your own string key/value data. Never used for Rieck business logic.

Request exampleapplication/json

curl -X POST https://api.rieckflow.com/v1/subscriptions/9b2f1c1e-…/usage \
  -H "Authorization: Bearer $RIECK_API_KEY" \
  -H "Idempotency-Key: order-2041" \
  -H "Content-Type: application/json" \
  -d '{
    "unit": "…",
    "quantity": 1,
    "unitPriceOere": 125000
  }'

const svar = await rieck.request("POST", "/v1/subscriptions/9b2f1c1e-…/usage", {
  body: {
    "unit": "…",
    "quantity": 1,
    "unitPriceOere": 125000
  },
});

{
  "data": {
    "id": "9b2f1c1e-6b87-4d9b-91a0-47c8d72b8440",
    "customerId": "467a0d8d-b9b2-4df3-bf7b-17d649442890",
    "customerName": "Acme ApS",
    "name": "Monthly service",
    "interval": {
      "unit": "month",
      "count": 1
    },
    "startDate": "2026-08-01",
    "endDate": null,
    "nextInvoiceDate": "2026-09-01",
    "dueDays": 14,
    "autoSend": true,
    "status": "active",
    "lines": [
      {
        "description": "Monthly service",
        "quantity": 1,
        "unitPriceOere": 125000,
        "vatRateBps": 2500
      }
    ],
    "invoiceCount": 1,
    "periodsBehind": 0,
    "latestInvoice": {
      "invoiceId": "5c0d10ec-f086-48c6-b1c7-b389a47ac6d1",
      "invoiceNumber": 1042,
      "periodDate": "2026-08-01"
    },
    "externalReference": "subscription-88",
    "metadata": null,
    "createdAt": "2026-08-01T08:00:00Z"
  }
}

201 Success envelopeapplication/json

Response fields 5

Field	Type	Description
`data.id`	`uuid`	Stable subscription id.
`data.interval`	`object`	Billing cadence unit and count.
`data.nextInvoiceDate`	`date`	Next period the engine will invoice.
`data.status`	`active \| paused \| cancelled`	Current subscription state.
`data.periodsBehind`	`integer`	Unprocessed periods. Zero means on schedule.

Possible errors 10

HTTP	Code	Meaning
400	`invalid_idempotency_key`	Idempotency-Key is missing or malformed.
400	`invalid_request`	The request body or parameter failed validation.
401	`invalid_api_key`	The API key is missing, invalid, expired or revoked.
403	`api_not_included`	The organisation’s plan does not include API access.
403	`insufficient_scope`	The key does not have the required scope.
404	`subscription_not_found`	The subscription does not exist or belongs to another organisation.
409	`idempotency_conflict`	The same key was used with a different request.
409	`idempotency_in_progress`	The same operation is currently being processed. Retry later.
413	`payload_too_large`	The JSON or uploaded file exceeds this endpoint’s size limit.
429	`rate_limited`	The organisation’s rate budget is exhausted.

Request body — fuldt JSON Schema

{
  "type": "object",
  "properties": {
    "unit": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20
    },
    "quantity": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 1000000000
    },
    "unitPriceOere": {
      "type": "integer",
      "minimum": 0,
      "maximum": 100000000
    },
    "idempotencyKey": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        {
          "type": "null"
        }
      ]
    },
    "period": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        {
          "type": "null"
        }
      ]
    },
    "metadata": {
      "anyOf": [
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "type": "string"
          }
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "unit",
    "quantity",
    "unitPriceOere"
  ],
  "additionalProperties": false
}

GET `/v1/subscriptions/{subscriptionId}/meters`

Real-time usage balance

subscriptions:read

What the customer has used RIGHT NOW, per meter — without waiting for an invoice. The number comes from exactly the query the invoicing uses, so the balance and the bill can never disagree. The list is what is UNBILLED: a subscription that has just run returns an empty list, not the period’s history.

Parameter	In	Type	Required	Description
`subscriptionId`	path	`string`	Yes

Request exampleNo request body

curl https://api.rieckflow.com/v1/subscriptions/9b2f1c1e-…/meters \
  -H "Authorization: Bearer $RIECK_API_KEY"

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

{
  "data": {
    "id": "9b2f1c1e-6b87-4d9b-91a0-47c8d72b8440",
    "customerId": "467a0d8d-b9b2-4df3-bf7b-17d649442890",
    "customerName": "Acme ApS",
    "name": "Monthly service",
    "interval": {
      "unit": "month",
      "count": 1
    },
    "startDate": "2026-08-01",
    "endDate": null,
    "nextInvoiceDate": "2026-09-01",
    "dueDays": 14,
    "autoSend": true,
    "status": "active",
    "lines": [
      {
        "description": "Monthly service",
        "quantity": 1,
        "unitPriceOere": 125000,
        "vatRateBps": 2500
      }
    ],
    "invoiceCount": 1,
    "periodsBehind": 0,
    "latestInvoice": {
      "invoiceId": "5c0d10ec-f086-48c6-b1c7-b389a47ac6d1",
      "invoiceNumber": 1042,
      "periodDate": "2026-08-01"
    },
    "externalReference": "subscription-88",
    "metadata": null,
    "createdAt": "2026-08-01T08:00:00Z"
  }
}

200 Success envelopeapplication/json

Response fields 5

Field	Type	Description
`data.id`	`uuid`	Stable subscription id.
`data.interval`	`object`	Billing cadence unit and count.
`data.nextInvoiceDate`	`date`	Next period the engine will invoice.
`data.status`	`active \| paused \| cancelled`	Current subscription state.
`data.periodsBehind`	`integer`	Unprocessed periods. Zero means on schedule.

Possible errors 5

HTTP	Code	Meaning
401	`invalid_api_key`	The API key is missing, invalid, expired or revoked.
403	`api_not_included`	The organisation’s plan does not include API access.
403	`insufficient_scope`	The key does not have the required scope.
404	`subscription_not_found`	The subscription does not exist or belongs to another organisation.
429	`rate_limited`	The organisation’s rate budget is exhausted.

POST `/v1/subscriptions/{subscriptionId}/meters/{meterId}/events`

Report a raw meter event

subscriptions:write

Send ONE raw event; we aggregate (sum/count/last) and price it — including tiered and package prices. This is the difference from /usage, which takes a FINISHED number you summed and priced yourself: if that number is wrong, we cannot see it. occurredAt is the event’s OWN timestamp, not the time we received it — a nightly batch MUST set it, or yesterday’s events land in today’s period and a last meter bills the wrong reading. A repeat of idempotencyKey returns the FIRST row id with duplicate:true and status 200, not a 409.

Parameter	In	Type	Required	Description
`subscriptionId`	path	`string`	Yes
`meterId`	path	`string`	Yes

Request body fields 4

Field	Type	Required	Description
`value`	`number`	No	Field in the request payload.
`occurredAt`	`string`	No	Field in the request payload.
`idempotencyKey`	`string`	No	Field in the request payload.
`metadata`	`object`	No	Your own string key/value data. Never used for Rieck business logic.

Request exampleapplication/json

curl -X POST https://api.rieckflow.com/v1/subscriptions/9b2f1c1e-…/meters/9b2f1c1e-…/events \
  -H "Authorization: Bearer $RIECK_API_KEY" \
  -H "Idempotency-Key: order-2041" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 1
  }'

const svar = await rieck.request("POST", "/v1/subscriptions/9b2f1c1e-…/meters/9b2f1c1e-…/events", {
  body: {
    "value": 1
  },
});

{
  "data": {
    "id": "9b2f1c1e-6b87-4d9b-91a0-47c8d72b8440",
    "customerId": "467a0d8d-b9b2-4df3-bf7b-17d649442890",
    "customerName": "Acme ApS",
    "name": "Monthly service",
    "interval": {
      "unit": "month",
      "count": 1
    },
    "startDate": "2026-08-01",
    "endDate": null,
    "nextInvoiceDate": "2026-09-01",
    "dueDays": 14,
    "autoSend": true,
    "status": "active",
    "lines": [
      {
        "description": "Monthly service",
        "quantity": 1,
        "unitPriceOere": 125000,
        "vatRateBps": 2500
      }
    ],
    "invoiceCount": 1,
    "periodsBehind": 0,
    "latestInvoice": {
      "invoiceId": "5c0d10ec-f086-48c6-b1c7-b389a47ac6d1",
      "invoiceNumber": 1042,
      "periodDate": "2026-08-01"
    },
    "externalReference": "subscription-88",
    "metadata": null,
    "createdAt": "2026-08-01T08:00:00Z"
  }
}

200 Success envelopeapplication/json

Response fields 5

Field	Type	Description
`data.id`	`uuid`	Stable subscription id.
`data.interval`	`object`	Billing cadence unit and count.
`data.nextInvoiceDate`	`date`	Next period the engine will invoice.
`data.status`	`active \| paused \| cancelled`	Current subscription state.
`data.periodsBehind`	`integer`	Unprocessed periods. Zero means on schedule.

Possible errors 10

HTTP	Code	Meaning
400	`invalid_idempotency_key`	Idempotency-Key is missing or malformed.
400	`invalid_request`	The request body or parameter failed validation.
401	`invalid_api_key`	The API key is missing, invalid, expired or revoked.
403	`api_not_included`	The organisation’s plan does not include API access.
403	`insufficient_scope`	The key does not have the required scope.
404	`subscription_not_found`	The subscription does not exist or belongs to another organisation.
409	`idempotency_conflict`	The same key was used with a different request.
409	`idempotency_in_progress`	The same operation is currently being processed. Retry later.
413	`payload_too_large`	The JSON or uploaded file exceeds this endpoint’s size limit.
429	`rate_limited`	The organisation’s rate budget is exhausted.

Request body — fuldt JSON Schema

{
  "type": "object",
  "properties": {
    "value": {
      "default": 1,
      "type": "number",
      "minimum": 0,
      "maximum": 1000000000
    },
    "occurredAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ]
    },
    "idempotencyKey": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        {
          "type": "null"
        }
      ]
    },
    "metadata": {
      "anyOf": [
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "type": "string"
          }
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "additionalProperties": false
}

POST `/v1/subscriptions/{subscriptionId}/preview`

Preview a change (no side effects)

subscriptions:read

Computes the prorated difference for a proposed set of lines WITHOUT changing anything. ⚠️ Send the returned prorationDate back when you save the change — two different proration dates give two different amounts. proration: null is a valid answer: the creditor uses none, nothing has been invoiced yet, or the change does not trigger proration. A NEGATIVE amount is a CREDIT, never a refund. POST rather than GET because line descriptions are customer data and must not end up in a URL.

Parameter	In	Type	Required	Description
`subscriptionId`	path	`string`	Yes

Request body fields 7

Field	Type	Required	Description
`lines`	`object[]`	Yes	Invoice or subscription line items.
`lines[].description`	`string`	Yes	Human-readable description.
`lines[].quantity`	`number`	Yes	Positive quantity for this line.
`lines[].unitPriceOere`	`integer`	Yes	Unit price in integer øre.
`lines[].vatRateBps`	`integer`	No	VAT rate in basis points. 2500 means 25%.
`lines[].vatExemptionReason`	`string`	No	Required legal reason when the VAT rate is zero.
`prorationDate`	`string`	No	Field in the request payload.

Request exampleapplication/json

curl -X POST https://api.rieckflow.com/v1/subscriptions/9b2f1c1e-…/preview \
  -H "Authorization: Bearer $RIECK_API_KEY" \
  -H "Idempotency-Key: order-2041" \
  -H "Content-Type: application/json" \
  -d '{
    "lines": [
      {
        "description": "Consulting",
        "quantity": 1,
        "unitPriceOere": 125000,
        "vatRateBps": 2500
      }
    ],
    "prorationDate": "2026-08-15"
  }'

const svar = await rieck.request("POST", "/v1/subscriptions/9b2f1c1e-…/preview", {
  body: {
    "lines": [
      {
        "description": "Consulting",
        "quantity": 1,
        "unitPriceOere": 125000,
        "vatRateBps": 2500
      }
    ],
    "prorationDate": "2026-08-15"
  },
});

{
  "data": {
    "id": "9b2f1c1e-6b87-4d9b-91a0-47c8d72b8440",
    "customerId": "467a0d8d-b9b2-4df3-bf7b-17d649442890",
    "customerName": "Acme ApS",
    "name": "Monthly service",
    "interval": {
      "unit": "month",
      "count": 1
    },
    "startDate": "2026-08-01",
    "endDate": null,
    "nextInvoiceDate": "2026-09-01",
    "dueDays": 14,
    "autoSend": true,
    "status": "active",
    "lines": [
      {
        "description": "Monthly service",
        "quantity": 1,
        "unitPriceOere": 125000,
        "vatRateBps": 2500
      }
    ],
    "invoiceCount": 1,
    "periodsBehind": 0,
    "latestInvoice": {
      "invoiceId": "5c0d10ec-f086-48c6-b1c7-b389a47ac6d1",
      "invoiceNumber": 1042,
      "periodDate": "2026-08-01"
    },
    "externalReference": "subscription-88",
    "metadata": null,
    "createdAt": "2026-08-01T08:00:00Z"
  }
}

200 Success envelopeapplication/json

Response fields 5

Field	Type	Description
`data.id`	`uuid`	Stable subscription id.
`data.interval`	`object`	Billing cadence unit and count.
`data.nextInvoiceDate`	`date`	Next period the engine will invoice.
`data.status`	`active \| paused \| cancelled`	Current subscription state.
`data.periodsBehind`	`integer`	Unprocessed periods. Zero means on schedule.

Possible errors 10

HTTP	Code	Meaning
400	`invalid_idempotency_key`	Idempotency-Key is missing or malformed.
400	`invalid_request`	The request body or parameter failed validation.
401	`invalid_api_key`	The API key is missing, invalid, expired or revoked.
403	`api_not_included`	The organisation’s plan does not include API access.
403	`insufficient_scope`	The key does not have the required scope.
404	`subscription_not_found`	The subscription does not exist or belongs to another organisation.
409	`idempotency_conflict`	The same key was used with a different request.
409	`idempotency_in_progress`	The same operation is currently being processed. Retry later.
413	`payload_too_large`	The JSON or uploaded file exceeds this endpoint’s size limit.
429	`rate_limited`	The organisation’s rate budget is exhausted.

Request body — fuldt JSON Schema

{
  "type": "object",
  "properties": {
    "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
      }
    },
    "prorationDate": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "lines"
  ],
  "additionalProperties": false
}

POST `/v1/subscriptions/{subscriptionId}/payment_method_session`

Start a card enrolment session

subscriptions:write

Returns a single-use URL you send your own user to. Card fields exist only on our checkout page. Also covers RENEWING an expiring card. The link expires in 2 hours and dies on first use. An optional returnUrl must point at one of your VERIFIED embed origins (422 return_url_not_allowed otherwise).

Parameter	In	Type	Required	Description
`subscriptionId`	path	`string`	Yes

Request body fields 2

Field	Type	Required	Description
`returnUrl`	`string`	No	Field in the request payload.
`locale`	`string`	No	Field in the request payload.

Request exampleapplication/json

curl -X POST https://api.rieckflow.com/v1/subscriptions/9b2f1c1e-…/payment_method_session \
  -H "Authorization: Bearer $RIECK_API_KEY" \
  -H "Idempotency-Key: order-2041" \
  -H "Content-Type: application/json" \
  -d '{}'

const svar = await rieck.request("POST", "/v1/subscriptions/9b2f1c1e-…/payment_method_session", {
  body: {},
});

{
  "data": {
    "id": "9b2f1c1e-6b87-4d9b-91a0-47c8d72b8440",
    "customerId": "467a0d8d-b9b2-4df3-bf7b-17d649442890",
    "customerName": "Acme ApS",
    "name": "Monthly service",
    "interval": {
      "unit": "month",
      "count": 1
    },
    "startDate": "2026-08-01",
    "endDate": null,
    "nextInvoiceDate": "2026-09-01",
    "dueDays": 14,
    "autoSend": true,
    "status": "active",
    "lines": [
      {
        "description": "Monthly service",
        "quantity": 1,
        "unitPriceOere": 125000,
        "vatRateBps": 2500
      }
    ],
    "invoiceCount": 1,
    "periodsBehind": 0,
    "latestInvoice": {
      "invoiceId": "5c0d10ec-f086-48c6-b1c7-b389a47ac6d1",
      "invoiceNumber": 1042,
      "periodDate": "2026-08-01"
    },
    "externalReference": "subscription-88",
    "metadata": null,
    "createdAt": "2026-08-01T08:00:00Z"
  }
}

200 Success envelopeapplication/json

Response fields 5

Field	Type	Description
`data.id`	`uuid`	Stable subscription id.
`data.interval`	`object`	Billing cadence unit and count.
`data.nextInvoiceDate`	`date`	Next period the engine will invoice.
`data.status`	`active \| paused \| cancelled`	Current subscription state.
`data.periodsBehind`	`integer`	Unprocessed periods. Zero means on schedule.

Possible errors 10

HTTP	Code	Meaning
400	`invalid_idempotency_key`	Idempotency-Key is missing or malformed.
400	`invalid_request`	The request body or parameter failed validation.
401	`invalid_api_key`	The API key is missing, invalid, expired or revoked.
403	`api_not_included`	The organisation’s plan does not include API access.
403	`insufficient_scope`	The key does not have the required scope.
404	`subscription_not_found`	The subscription does not exist or belongs to another organisation.
409	`idempotency_conflict`	The same key was used with a different request.
409	`idempotency_in_progress`	The same operation is currently being processed. Retry later.
413	`payload_too_large`	The JSON or uploaded file exceeds this endpoint’s size limit.
429	`rate_limited`	The organisation’s rate budget is exhausted.

Request body — fuldt JSON Schema

{
  "type": "object",
  "properties": {
    "returnUrl": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 2000,
          "format": "uri"
        },
        {
          "type": "null"
        }
      ]
    },
    "locale": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "da",
            "en"
          ]
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "additionalProperties": false
}

GET `/v1/subscriptions/{subscriptionId}/payment_method`

Get the stored payment method

subscriptions:read

Parameter	In	Type	Required	Description
`subscriptionId`	path	`string`	Yes

Request exampleNo request body

curl https://api.rieckflow.com/v1/subscriptions/9b2f1c1e-…/payment_method \
  -H "Authorization: Bearer $RIECK_API_KEY"

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

{
  "data": {
    "id": "9b2f1c1e-6b87-4d9b-91a0-47c8d72b8440",
    "customerId": "467a0d8d-b9b2-4df3-bf7b-17d649442890",
    "customerName": "Acme ApS",
    "name": "Monthly service",
    "interval": {
      "unit": "month",
      "count": 1
    },
    "startDate": "2026-08-01",
    "endDate": null,
    "nextInvoiceDate": "2026-09-01",
    "dueDays": 14,
    "autoSend": true,
    "status": "active",
    "lines": [
      {
        "description": "Monthly service",
        "quantity": 1,
        "unitPriceOere": 125000,
        "vatRateBps": 2500
      }
    ],
    "invoiceCount": 1,
    "periodsBehind": 0,
    "latestInvoice": {
      "invoiceId": "5c0d10ec-f086-48c6-b1c7-b389a47ac6d1",
      "invoiceNumber": 1042,
      "periodDate": "2026-08-01"
    },
    "externalReference": "subscription-88",
    "metadata": null,
    "createdAt": "2026-08-01T08:00:00Z"
  }
}

200 Masked card, type, expiry, provider and whether it is bound to THIS subscription. data is null when there is none.application/json

Response fields 5

Field	Type	Description
`data.id`	`uuid`	Stable subscription id.
`data.interval`	`object`	Billing cadence unit and count.
`data.nextInvoiceDate`	`date`	Next period the engine will invoice.
`data.status`	`active \| paused \| cancelled`	Current subscription state.
`data.periodsBehind`	`integer`	Unprocessed periods. Zero means on schedule.

Possible errors 5

HTTP	Code	Meaning
401	`invalid_api_key`	The API key is missing, invalid, expired or revoked.
403	`api_not_included`	The organisation’s plan does not include API access.
403	`insufficient_scope`	The key does not have the required scope.
404	`subscription_not_found`	The subscription does not exist or belongs to another organisation.
429	`rate_limited`	The organisation’s rate budget is exhausted.

DELETE `/v1/subscriptions/{subscriptionId}/payment_method`

Detach the card

subscriptions:write

Only a card bound to THIS subscription is detached. A customer-wide default card is shared with her other agreements and returns 409 payment_method_not_bound.

Parameter	In	Type	Required	Description
`subscriptionId`	path	`string`	Yes

Request exampleNo request body

curl -X DELETE https://api.rieckflow.com/v1/subscriptions/9b2f1c1e-…/payment_method \
  -H "Authorization: Bearer $RIECK_API_KEY" \
  -H "Idempotency-Key: order-2041"

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

{
  "data": {
    "id": "9b2f1c1e-6b87-4d9b-91a0-47c8d72b8440",
    "customerId": "467a0d8d-b9b2-4df3-bf7b-17d649442890",
    "customerName": "Acme ApS",
    "name": "Monthly service",
    "interval": {
      "unit": "month",
      "count": 1
    },
    "startDate": "2026-08-01",
    "endDate": null,
    "nextInvoiceDate": "2026-09-01",
    "dueDays": 14,
    "autoSend": true,
    "status": "active",
    "lines": [
      {
        "description": "Monthly service",
        "quantity": 1,
        "unitPriceOere": 125000,
        "vatRateBps": 2500
      }
    ],
    "invoiceCount": 1,
    "periodsBehind": 0,
    "latestInvoice": {
      "invoiceId": "5c0d10ec-f086-48c6-b1c7-b389a47ac6d1",
      "invoiceNumber": 1042,
      "periodDate": "2026-08-01"
    },
    "externalReference": "subscription-88",
    "metadata": null,
    "createdAt": "2026-08-01T08:00:00Z"
  }
}

200 Success envelopeapplication/json

Response fields 5

Field	Type	Description
`data.id`	`uuid`	Stable subscription id.
`data.interval`	`object`	Billing cadence unit and count.
`data.nextInvoiceDate`	`date`	Next period the engine will invoice.
`data.status`	`active \| paused \| cancelled`	Current subscription state.
`data.periodsBehind`	`integer`	Unprocessed periods. Zero means on schedule.

Possible errors 8

HTTP	Code	Meaning
400	`invalid_idempotency_key`	Idempotency-Key is missing or malformed.
401	`invalid_api_key`	The API key is missing, invalid, expired or revoked.
403	`api_not_included`	The organisation’s plan does not include API access.
403	`insufficient_scope`	The key does not have the required scope.
404	`subscription_not_found`	The subscription does not exist or belongs to another organisation.
409	`idempotency_conflict`	The same key was used with a different request.
409	`idempotency_in_progress`	The same operation is currently being processed. Retry later.
429	`rate_limited`	The organisation’s rate budget is exhausted.

Subscriptions

GET /v1/subscriptions

POST /v1/subscriptions

GET /v1/subscriptions/{subscriptionId}

PATCH /v1/subscriptions/{subscriptionId}

POST /v1/subscriptions/{subscriptionId}/pause

POST /v1/subscriptions/{subscriptionId}/resume

POST /v1/subscriptions/{subscriptionId}/cancel

GET /v1/subscriptions/{subscriptionId}/invoices

GET /v1/subscriptions/{subscriptionId}/next_invoice

POST /v1/subscriptions/{subscriptionId}/run

POST /v1/subscriptions/{subscriptionId}/usage

GET /v1/subscriptions/{subscriptionId}/meters

POST /v1/subscriptions/{subscriptionId}/meters/{meterId}/events

POST /v1/subscriptions/{subscriptionId}/preview

POST /v1/subscriptions/{subscriptionId}/payment_method_session

GET /v1/subscriptions/{subscriptionId}/payment_method

DELETE /v1/subscriptions/{subscriptionId}/payment_method

GET `/v1/subscriptions`

POST `/v1/subscriptions`

GET `/v1/subscriptions/{subscriptionId}`

PATCH `/v1/subscriptions/{subscriptionId}`

POST `/v1/subscriptions/{subscriptionId}/pause`

POST `/v1/subscriptions/{subscriptionId}/resume`

POST `/v1/subscriptions/{subscriptionId}/cancel`

GET `/v1/subscriptions/{subscriptionId}/invoices`

GET `/v1/subscriptions/{subscriptionId}/next_invoice`

POST `/v1/subscriptions/{subscriptionId}/run`

POST `/v1/subscriptions/{subscriptionId}/usage`

GET `/v1/subscriptions/{subscriptionId}/meters`

POST `/v1/subscriptions/{subscriptionId}/meters/{meterId}/events`

POST `/v1/subscriptions/{subscriptionId}/preview`

POST `/v1/subscriptions/{subscriptionId}/payment_method_session`

GET `/v1/subscriptions/{subscriptionId}/payment_method`

DELETE `/v1/subscriptions/{subscriptionId}/payment_method`