Create and manage subscriptions

Model a recurring offer, start a subscription payment flow, and review its lifecycle with the REST API.

A subscription connects a PayNowPro customer to a recurring price on a product. Set up the customer and catalog first, then create a subscription intent to begin the payment flow.

1. Create or locate the customer

Every subscription needs both PayNowPro's customer ID and your stable customer identifier.

curl -X POST "https://api.paynowpro.com/api/v1/customers" \
  -H "api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "tenantAlias": "YOUR_TENANT_ALIAS",
    "associatedId": "user_123",
    "firstName": "Avery",
    "lastName": "Brown",
    "email": "avery@example.com"
  }'

Save the returned PayNowPro customer id beside your associatedId. The subscription API uses both values.

2. Create a recurring product and price

A product describes what you sell. A recurring price supplies the amount, lowercase ISO 4217 currency code, and billing frequency.

curl -X POST "https://api.paynowpro.com/api/v1/products" \
  -H "api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "tenantAlias": "YOUR_TENANT_ALIAS",
    "name": "Pro membership",
    "description": "Monthly access to the Pro plan",
    "active": true,
    "prices": [{
      "details": { "amount": 25, "currency": "usd" },
      "recurring": { "frequency": "Monthly" }
    }]
  }'

The response includes the product and price IDs. Store both. Supported recurring frequencies are Daily, Weekly, Fortnightly, Monthly, BiMonthly, Quarterly, and Yearly. A recurring price may also include an optional period and executionDate; see Prices before using either field.

3. Start the subscription payment flow

Create a subscription intent on your server. The response includes the payment intent ID that your payment-flow integration uses to continue checkout.

curl -X POST "https://api.paynowpro.com/api/v1/subscriptions/intent" \
  -H "api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "tenantAlias": "YOUR_TENANT_ALIAS",
    "customerId": "CUSTOMER_ID",
    "associatedCustomerId": "user_123",
    "productId": "PRODUCT_ID",
    "priceId": "PRICE_ID",
    "receiptUrl": "https://example.com/billing/user_123/receipt",
    "returnUrl": "https://example.com/billing/user_123/complete"
  }'

Your application should not grant subscription access solely because the customer returned to returnUrl. Confirm the payment and subscription outcome with the supported account flow before granting access.

4. Read and manage the lifecycle

Use the REST API to retrieve, list, cancel, and audit subscriptions for a customer.

curl "https://api.paynowpro.com/api/v1/subscriptions/active?tenantAlias=YOUR_TENANT_ALIAS&customer=CUSTOMER_ID" \
  -H "api-key: YOUR_API_KEY"

curl "https://api.paynowpro.com/api/v1/subscriptions/SUBSCRIPTION_ID?tenantAlias=YOUR_TENANT_ALIAS&customer=CUSTOMER_ID" \
  -H "api-key: YOUR_API_KEY"

curl "https://api.paynowpro.com/api/v1/subscriptions?tenantAlias=YOUR_TENANT_ALIAS&customer=CUSTOMER_ID&startDate=2026-01-01&endDate=2026-12-31" \
  -H "api-key: YOUR_API_KEY"

curl -X DELETE "https://api.paynowpro.com/api/v1/subscriptions/SUBSCRIPTION_ID?tenantAlias=YOUR_TENANT_ALIAS&customer=CUSTOMER_ID" \
  -H "api-key: YOUR_API_KEY"

A subscription record can include its product, price, payment-intent, first-billing-date, next-billing-date, successful-billing count, and cancellation date. Subscription change records identify an upgrade or downgrade and report pending, successful, or failed status.

Organize plans with product groups

Use a product group to relate plans that belong to one offering. The prorateUpgrades setting controls whether eligible upgrades in that group are prorated. Treat a plan change as complete only after you receive the final subscription-change result for your integration.

Read Product groups, Subscriptions, and the Subscriptions API reference before implementing plan changes.