@deliverart/sdk-js-subscription

Subscription management package for the Deliverart JavaScript SDK.

Highlights

• subscription plan CRUD for backoffice/admin flows
• public catalog for purchasable subscription plans
• initial subscription purchase flow with payment start and offline payment resolution
• subscription CRUD for infinite, consumption and time_based
• renewal CRUD for consumption and time_based
• subscription overview from point of sale
• admin billing queue and billing overview
• credit adjustments for consumption subscriptions
• renewal payment initialization for stripe and bank_transfer
• manual renewal payment resolution for offline payment methods
• purchase lifecycle actions: cancel, retry_payment, refund
• renewal lifecycle actions: cancel, retry_payment, refund

Subscription Plan Catalog

import { GetSubscriptionPlanCatalog } from '@deliverart/sdk-js-subscription'

const plans = await sdk.call(new GetSubscriptionPlanCatalog())

Each catalog item exposes the plan configuration plus priceOptions, already sorted by threshold.

Preview the self-service charge before creating a purchase:

import { CalculateSubscriptionPlanPurchaseQuote } from '@deliverart/sdk-js-subscription'

const quote = await sdk.call(
  new CalculateSubscriptionPlanPurchaseQuote('plan-id', {
    pointOfSale: '/point_of_sales/pos-id',
    startsAt: '2026-04-05',
  }),
)

The response includes threshold, unitPrice, amount, type, startsAt and the effective autoRenewal.

Admin Plan Assignment

Assign a plan directly to a point of sale without going through the public purchase flow:

import { AssignSubscriptionPlan } from '@deliverart/sdk-js-subscription'

const subscription = await sdk.call(
  new AssignSubscriptionPlan('plan-id', {
    pointOfSale: '/point_of_sales/pos-id',
    startsAt: '2026-04-01',
  }),
)

This operation is intended for admin/backoffice flows, including adminOnly and infinite plans.

Subscription Purchase

Create a purchase from a public plan:

import { CreateSubscriptionPurchase } from '@deliverart/sdk-js-subscription'

const purchase = await sdk.call(
  new CreateSubscriptionPurchase({
    pointOfSale: '/point_of_sales/pos-id',
    plan: '/subscription_plans/plan-id',
  }),
)

Start payment for the purchase:

import { PaySubscriptionPurchase } from '@deliverart/sdk-js-subscription'

const payment = await sdk.call(
  new PaySubscriptionPurchase('purchase-id', 'bank_transfer'),
)

Subscription billing is platform-level:

• order and ecommerce payments still use each POS payment configuration
• subscription purchases and renewals use the central platform billing account
• the SDK therefore accepts only stripe and bank_transfer for subscription payment start and retry

Resolve offline payment:

import { ResolveSubscriptionPurchasePayment } from '@deliverart/sdk-js-subscription'

await sdk.call(
  new ResolveSubscriptionPurchasePayment('purchase-id', {
    status: 'paid',
    response: 'verified by admin',
  }),
)

For bank_transfer, the purchase or renewal moves to pending_verification until a ROLE_SUBSCRIPTION_BILLING_ADMIN, ROLE_SUBSCRIPTION_ADMIN or ROLE_SUPER_ADMIN approves or rejects it.

Cancel a non-completed purchase:

import { CancelSubscriptionPurchase } from '@deliverart/sdk-js-subscription'

await sdk.call(
  new CancelSubscriptionPurchase('purchase-id', {
    response: 'customer cancelled before payment',
  }),
)

Retry a failed purchase payment:

import { RetrySubscriptionPurchasePayment } from '@deliverart/sdk-js-subscription'

const payment = await sdk.call(
  new RetrySubscriptionPurchasePayment('purchase-id', 'bank_transfer'),
)

If the retry method is bank_transfer, the returned purchase status becomes pending_verification.

Refund a completed offline purchase:

import { RefundSubscriptionPurchase } from '@deliverart/sdk-js-subscription'

await sdk.call(
  new RefundSubscriptionPurchase('purchase-id', {
    response: 'manual refund approved',
  }),
)

Renewal Payment Start

Consumption renewal:

import { PaySubscriptionConsumptionRenewal } from '@deliverart/sdk-js-subscription'

const payment = await sdk.call(
  new PaySubscriptionConsumptionRenewal('renewal-id', 'bank_transfer'),
)

Time-based renewal:

import { PaySubscriptionTimeBasedRenewal } from '@deliverart/sdk-js-subscription'

const payment = await sdk.call(
  new PaySubscriptionTimeBasedRenewal('renewal-id', 'stripe'),
)

Both requests return the same PaymentInfo shape used by the payment SDK area.

Renewal Payment Resolution

Consumption renewal:

import { ResolveSubscriptionConsumptionRenewalPayment } from '@deliverart/sdk-js-subscription'

await sdk.call(
  new ResolveSubscriptionConsumptionRenewalPayment('renewal-id', {
    status: 'paid',
    response: 'verified by admin',
  }),
)

Time-based renewal:

import { ResolveSubscriptionTimeBasedRenewalPayment } from '@deliverart/sdk-js-subscription'

await sdk.call(
  new ResolveSubscriptionTimeBasedRenewalPayment('renewal-id', {
    status: 'failed',
    response: 'bank transfer rejected',
  }),
)

Allowed statuses are paid, failed and canceled.

The renewal must typically be in pending_verification before manual approval.

Admin Billing Read Models

Pending verification queue:

import { GetSubscriptionBillingPendingVerification } from '@deliverart/sdk-js-subscription'

const queue = await sdk.call(
  new GetSubscriptionBillingPendingVerification({
    query: {
      kind: 'purchase',
      olderThanHours: 24,
      limit: 20,
    },
  }),
)

Billing overview counters:

import { GetSubscriptionBillingOverview } from '@deliverart/sdk-js-subscription'

const overview = await sdk.call(new GetSubscriptionBillingOverview())

The overview payload exposes:

• pending verification counts for purchases and renewals
• failed payment counts
• open purchase counts
• pending renewal counts
• a queuePreview array with the same item shape returned by the pending verification queue

Renewal Lifecycle Actions

Consumption renewal:

import {
  CancelSubscriptionConsumptionRenewal,
  RetrySubscriptionConsumptionRenewalPayment,
  RefundSubscriptionConsumptionRenewal,
} from '@deliverart/sdk-js-subscription'

await sdk.call(
  new CancelSubscriptionConsumptionRenewal('renewal-id', {
    response: 'operator canceled renewal',
  }),
)

const payment = await sdk.call(
  new RetrySubscriptionConsumptionRenewalPayment('renewal-id', 'bank_transfer'),
)

await sdk.call(
  new RefundSubscriptionConsumptionRenewal('renewal-id', {
    response: 'manual credit refund',
  }),
)

Time-based renewal:

import {
  CancelSubscriptionTimeBasedRenewal,
  RetrySubscriptionTimeBasedRenewalPayment,
  RefundSubscriptionTimeBasedRenewal,
} from '@deliverart/sdk-js-subscription'

await sdk.call(
  new CancelSubscriptionTimeBasedRenewal('renewal-id', {
    response: 'operator canceled renewal',
  }),
)

const payment = await sdk.call(
  new RetrySubscriptionTimeBasedRenewalPayment('renewal-id', 'bank_transfer'),
)

await sdk.call(
  new RefundSubscriptionTimeBasedRenewal('renewal-id', {
    response: 'manual time-based refund',
  }),
)

cancel and retry_payment are for non-completed renewals. refund is for completed offline renewals and returns a lifecycle summary including payment info plus rolled-back credits or restored expiration.

Renewal Payment Relation

Renewal list/detail schemas now expose the linked payment IRI when a payment attempt already exists.