> ## Documentation Index > Fetch the complete documentation index at: https://docs.orsunpay.com/llms.txt > Use this file to discover all available pages before exploring further. # notifications for a usage subscription > Scoped to the merchant API key and test/live mode. Setup creates a hosted Stripe consent link; it does not authorize a charge. Unknown payment outcomes must be reconciled before recovery. ## OpenAPI ````yaml /openapi.json post /v1/usage-billing/subscriptions/{id}/notifications openapi: 3.1.0 info: contact: name: OrsunPay description: >- Server-to-server merchant payments. Money is always a decimal string in major units. title: OrsunPay Merchant API version: '1.0' servers: [] security: [] tags: - description: Poll stored merchant transaction status name: Transactions - description: Create merchant sales and payouts name: Payments - description: Request refunds and read stored refund outcomes name: Refunds - description: Signed merchant event deliveries name: Webhooks - description: Create, list and deactivate shareable merchant payment links name: Payment links paths: /v1/usage-billing/subscriptions/{id}/notifications: post: tags: - Usage billing summary: notifications for a usage subscription description: >- Scoped to the merchant API key and test/live mode. Setup creates a hosted Stripe consent link; it does not authorize a charge. Unknown payment outcomes must be reconciled before recovery. operationId: notificationsUsageSubscription parameters: - in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UsageNotificationsDto' required: true responses: '200': content: application/json: example: data: autoRenewEnabled: false cancelAtPeriodEnd: false createdAt: '2026-10-13T12:00:00.000Z' currency: EUR customerRef: customer_123 id: 22222222-2222-4222-8222-222222222222 includedCredits: '1000' monthlyPrice: '20.00' notificationEmailConfigured: false notificationEnabled: false notificationLocale: en overageAmount: '0.00' overageCredits: '0' overageLimit: '10.00' overageUnitPrice: '0.01' paymentState: pay_by_link periodEnd: null periodStart: null planId: 11111111-1111-4111-8111-111111111111 planName: Starter remainingCredits: '0' status: pending_payment unit: request usedCredits: '0' schema: properties: data: $ref: '#/components/schemas/UsageSubscriptionResponseDto' required: - data type: object description: The scoped resource. Duplicate creates return the original resource. headers: RateLimit: description: >- Remaining requests (r) and seconds to reset/full refill (t), per evaluated policy. Absent when disabled; merchant quota is omitted during Redis outages, while IP/auth protection uses replica memory. schema: example: '"merchant";r=37;t=4' type: string RateLimit-Policy: description: >- Evaluated policies (draft-ietf-httpapi-ratelimit-headers-11). q is burst quota; w is the full refill window in seconds. schema: example: '"merchant";q=100;w=5' type: string '400': content: application/json: example: errorCode: USAGE_INPUT_INVALID message: USAGE_INPUT_INVALID statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/ApiErrorResponseDto' - $ref: '#/components/schemas/ValidationErrorResponseDto' description: >- Invalid fields, decimal precision or missing idempotency key. USAGE_INPUT_INVALID / USAGE_AMOUNT_INVALID / USAGE_CREDITS_INVALID / USAGE_IDEMPOTENCY_KEY_REQUIRED. '401': content: application/json: example: error: Unauthorized message: Invalid API key statusCode: 401 schema: $ref: '#/components/schemas/UnauthorizedErrorResponseDto' description: Missing or invalid merchant API key. '403': content: application/json: example: errorCode: USAGE_SCOPE_INACTIVE statusCode: 403 schema: $ref: '#/components/schemas/ApiErrorResponseDto' description: >- USAGE_SCOPE_INACTIVE: the authenticated merchant or company is inactive. '404': content: application/json: example: errorCode: USAGE_SUBSCRIPTION_NOT_FOUND statusCode: 404 schema: $ref: '#/components/schemas/ApiErrorResponseDto' description: >- USAGE_PLAN_NOT_FOUND / USAGE_SUBSCRIPTION_NOT_FOUND; unknown or another shop/mode. '409': content: application/json: example: errorCode: USAGE_EVENT_CONFLICT statusCode: 409 schema: $ref: '#/components/schemas/ApiErrorResponseDto' description: >- USAGE_PLAN_CONFLICT / USAGE_EVENT_CONFLICT / USAGE_IDEMPOTENCY_CONFLICT / USAGE_SUBSCRIPTION_INACTIVE / USAGE_PERIOD_ENDED / USAGE_OVERAGE_LIMIT_EXCEEDED / USAGE_BUSY. '422': content: application/json: example: errorCode: IDEMPOTENCY_KEY_REUSED statusCode: 422 schema: $ref: '#/components/schemas/ApiErrorResponseDto' description: The request conflicts with a previously recorded idempotency key. '429': content: application/json: example: error: RATE_LIMITED errorCode: RATE_LIMITED message: Too many requests. Retry after the indicated delay. status: false statusCode: 429 schema: $ref: '#/components/schemas/ApiErrorResponseDto' description: >- RATE_LIMITED: IP, merchant or failed-auth quota exhausted, or auth-in-flight concurrency pressure (Retry-After: 1). Wait Retry-After seconds and retry with the same Idempotency-Key. headers: RateLimit: description: >- Remaining requests (r) and seconds to reset/full refill (t), per evaluated policy. Absent when disabled; merchant quota is omitted during Redis outages, while IP/auth protection uses replica memory. schema: example: '"merchant";r=37;t=4' type: string RateLimit-Policy: description: >- Evaluated policies (draft-ietf-httpapi-ratelimit-headers-11). q is burst quota; w is the full refill window in seconds. schema: example: '"merchant";q=100;w=5' type: string Retry-After: description: Minimum delay in whole seconds before retrying. schema: example: 1 minimum: 1 type: integer '502': content: application/json: example: errorCode: UPSTREAM_UNAVAILABLE statusCode: 502 schema: $ref: '#/components/schemas/ApiErrorResponseDto' description: 'UPSTREAM_UNAVAILABLE: retry the same intent.' '503': content: application/json: example: error: Service Unavailable message: API_KEY_VALIDATION_UNAVAILABLE statusCode: 503 schema: $ref: '#/components/schemas/AuthenticationUnavailableResponseDto' description: API key validation unavailable. '504': content: application/json: example: errorCode: UPSTREAM_TIMEOUT statusCode: 504 schema: $ref: '#/components/schemas/ApiErrorResponseDto' description: >- UPSTREAM_TIMEOUT: the operation may still complete; retry the same intent. security: - X-API-Key: [] components: schemas: UsageNotificationsDto: properties: email: description: >- Required when notifications are enabled. The address is not echoed in responses. format: email type: string enabled: type: boolean locale: enum: - en - uk type: string required: - enabled - locale type: object UsageSubscriptionResponseDto: properties: autoRenewEnabled: type: boolean cancelAtPeriodEnd: type: boolean createdAt: format: date-time type: string currency: type: string customerRef: type: string id: type: string includedCredits: type: string monthlyPrice: pattern: ^(0|[1-9]\d{0,19})(\.\d{1,18})?$ type: string notificationEmailConfigured: type: boolean notificationEnabled: type: boolean notificationLocale: enum: - en - uk type: string overageAmount: pattern: ^(0|[1-9]\d{0,19})(\.\d{1,18})?$ type: string overageCredits: type: string overageLimit: pattern: ^(0|[1-9]\d{0,19})(\.\d{1,18})?$ type: string overageUnitPrice: pattern: ^(0|[1-9]\d{0,19})(\.\d{1,18})?$ type: string paymentState: description: Payment state; unknown cannot be retried as a new payment. type: string periodEnd: anyOf: - format: date-time type: string - type: 'null' periodStart: anyOf: - format: date-time type: string - type: 'null' planId: type: string planName: type: string remainingCredits: type: string status: enum: - pending_payment - active - past_due - cancelled type: string unit: type: string usedCredits: type: string required: - id - planId - customerRef - status - planName - unit - currency - monthlyPrice - includedCredits - overageUnitPrice - overageLimit - periodStart - periodEnd - usedCredits - remainingCredits - overageCredits - overageAmount - cancelAtPeriodEnd - autoRenewEnabled - paymentState - notificationEnabled - notificationEmailConfigured - notificationLocale - createdAt type: object ApiErrorResponseDto: properties: error: description: Same as errorCode example: DUPLICATE_ORDER_ID type: string errorCode: description: >- Machine-readable, extensible code. Known values: ADYEN_REFUSED, CARD_DATA_NOT_ACCEPTED, RATE_LIMITED, PAYMENT_LINK_INVALID_AMOUNT, PAYMENT_LINK_UNSUPPORTED_CURRENCY, PAYMENT_LINK_INVALID_EXPIRY, PAYMENT_LINK_INVALID_MAX_USES, PAYMENT_LINK_REDIRECT_URL_NOT_ALLOWED, PAYMENT_LINK_METADATA_TOO_LARGE, PAYMENT_LINK_INVALID_TEXT, PAYMENT_LINK_NOT_FOUND, PAYMENT_LINK_INVALID_LIMIT, PAYMENT_LINK_INVALID_CURSOR, API_KEY_ROTATION_REQUIRED, ORDER_ID_RESERVED, NO_CREDENTIALS_FOR_MODE, LIVEMODE_MISMATCH, PSP_OUTCOME_UNKNOWN, PAYMENT_METHOD_REQUIRED, PAYMENT_METHOD_INPUT_WITHOUT_METHOD, NO_PAYMENT_METHODS, IDEMPOTENCY_KEY_INVALID, DUPLICATE_ORDER_ID, IDEMPOTENCY_IN_PROGRESS, IDEMPOTENCY_KEY_REUSED, UPSTREAM_ERROR, UPSTREAM_UNAVAILABLE, UPSTREAM_TIMEOUT, REFUND_INVALID_AMOUNT, REFUND_INVALID_REASON, REFUND_INVALID_METADATA, REFUND_INPUT_INVALID, REFUND_EXCEEDS_AMOUNT, TRANSACTION_NOT_REFUNDABLE, REFUND_NOT_FOUND, REFUND_NOT_SUPPORTED, IDEMPOTENCY_LEASE_LOST, REFUND_SERVICE_UNAVAILABLE. New codes may be added; clients must handle unknown values. example: DUPLICATE_ORDER_ID type: string existingTransactionId: description: >- DUPLICATE_ORDER_ID only: the transaction that already uses this orderId example: tr_x8k2p0q5scocndpejk0nud75q type: string fields: description: >- Invalid or missing buyer contact fields for CUSTOMER_CONTACT_REQUIRED example: - customer.email - customer.country items: type: string type: array idempotencyKey: description: IDEMPOTENCY_* errors only example: 0b6f2c1e-4c7a-4a43-9a51-6a4b1d7e9f10 type: string message: example: A transaction with orderId "A-1001" already exists for this merchant type: string orderId: description: DUPLICATE_ORDER_ID only example: A-1001 type: string status: example: false type: boolean statusCode: example: 409 type: number required: - status - statusCode - errorCode - error - message type: object ValidationErrorResponseDto: properties: error: example: Bad Request type: string message: example: - >- amount must be a decimal string in major units, e.g. "12.30"; JSON numbers are not accepted for money (got 12.3) items: type: string type: array statusCode: example: 400 type: number required: - statusCode - error - message type: object UnauthorizedErrorResponseDto: properties: error: example: Unauthorized type: string errorCode: description: Stable authentication error code when available example: API_KEY_ROTATION_REQUIRED type: string message: example: Invalid API key type: string statusCode: description: HTTP status when included by the error handler example: 401 type: number required: - message type: object AuthenticationUnavailableResponseDto: properties: error: example: Service Unavailable type: string message: example: API_KEY_VALIDATION_UNAVAILABLE type: string statusCode: example: 503 type: number required: - statusCode - error - message type: object securitySchemes: X-API-Key: in: header name: x-api-key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.