Skip to main content
Migo Docs

Plans

A Plan is pricing configuration reused across subscriptions. Create it once, subscribe many cardholders to it.

Plan types (type enum)​

The Migo middleware models recurrence around four type values — they decide how Migo computes the next charge date. Send the lowercase camelCase value (the spec example renders the enum key in uppercase but the runtime accepts only the values shown below):

Enum keyAPI value (type)MeaningWhen to use
INTERVAL"interval"Charges every N days from the subscription's anchor dateMost common — weekly, every 30 days, every 90 days
FIXED_DAY"fixedDay"Charges on a specific day of the month"1st of the month" or "15th of every month" billing
ANNIVERSARY"anniversary"Charges on the same calendar day each cycle (handles month-length quirks)Yearly subscriptions, anniversary billing
AUTOMATIC"automatic"Migo defers next-charge calculation to the processor (legacy/manual)Rare; only for processors with their own scheduler

Source of truth: libs/mongo-database/src/lib/enums/plan.enum.ts.

Create a plan​

curl -X POST https://mw.migopayments.com/v1/plans \
  -H "Authorization: Bearer <middleware-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": {
      "name": "Pro Monthly",
      "amount": 29.99,
      "currency": "USD",
      "type": "interval",
      "frequency": {
        "frequency": 30,
        "day": 1,
        "shortDescription": "Monthly",
        "longDescription": "Charged every 30 days"
      },
      "methods": ["fac-2", "visa-cybersource"],
      "installments": [1],
      "autoRenewal": true,
      "dailyAttempts": 3,
      "daysNotifyExpiringCard": 7
    },
    "client": "client_abc123"
  }'
FieldTypeRequiredNotes
plan.namestring✅Shown on cardholder statements
plan.amountnumber✅Decimal, up to 4 places
plan.currencyISO 4217✅GTQ, USD, etc.
plan.typeenum—"interval" | "fixedDay" | "anniversary" | "automatic". Not required by validation; fixedDay only enforces frequency > 30
plan.frequency.frequencyinteger✅Days between charges (used by interval); 0 for fixedDay
plan.frequency.day1–28—Day of month, only relevant for fixedDay plans; not required by validation
plan.frequency.shortDescriptionstring✅One-word cadence label (e.g. Monthly)
plan.frequency.longDescriptionstring✅Full cadence description
plan.methodsstring[]✅Allowed processors for charges
plan.installmentsnumber[]✅Allowed installment counts ([1] for single-payment)
plan.autoRenewalboolean✅Whether Migo schedules the next charge automatically
plan.dailyAttemptsinteger✅Retry attempts per day on failed charges
plan.daysNotifyExpiringCardinteger✅Days before card expiry to notify the cardholder
clientstring✅Merchant client slug

The interval/intervalCount fields used by other billing platforms do not apply here — Migo derives cadence from type + frequency.frequency + frequency.day.

List plans​

curl "https://mw.migopayments.com/v1/plans/list?client=client_abc123" \
  -H "Authorization: Bearer <middleware-jwt>"

Get plan detail for a specific client​

curl "https://mw.migopayments.com/v1/plans/{planId}/client/{client}/detail" \
  -H "Authorization: Bearer <middleware-jwt>"

Returns the plan plus client-specific overrides (currency conversion, localized name, etc.) and the next charge date computed against the merchant's timezone.

Update a plan​

curl -X PUT https://mw.migopayments.com/v1/plans \
  -H "Authorization: Bearer <middleware-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "client": "client_abc123",
    "planId": "pln_01HXXX",
    "plan": {
      "name": "Pro Monthly",
      "amount": 34.99
    }
  }'

The fields to update must be nested under a plan object, and that object must carry the plan name (the handler reads body.plan.name). Sending amount at the top level has no effect.

warning

Updating a plan's amount or frequency does not change existing subscriptions — they continue at their original price/cadence. The API does not support changing a subscription's plan, so migrating existing subscriptions to the new pricing requires creating new subscriptions (via the verify-card flow).

Versioning​

You cannot delete a plan that has active subscriptions. Create a new plan and migrate subscriptions instead. This preserves historical billing accuracy.