Subscription Management

​

Overview

• Unlimited invoice and expense uploads
• CFDI XML parsing and validation
• Automatic payment matching
• RESTful API access (PRO and above)
• Secure data storage

​

Available Plans

​

FREE Plan

• Cost: $0 MXN/month
• Profiles: 1
• Invoices/Expenses: Unlimited
• Reports: Basic
• Support: Community
• Ideal for: Individual freelancers and testing

​

BASIC Plan

• Cost: $299 MXN/month or$2,999 MXN/year (save 17%)
• Profiles: 5
• Invoices/Expenses: Unlimited
• Reports: Complete with PDF export
• Public Reports: Up to 10 active tokens
• Support: Email
• Trial: 30 days
• Ideal for: Small businesses with multiple RFCs

​

PRO Plan

• Cost: $799 MXN/month or$7,999 MXN/year (save 17%)
• Profiles: 20
• Invoices/Expenses: Unlimited
• Reports: Advanced with Excel export
• Public Reports: Up to 50 active tokens
• SAT Download: FIEL/e.firma bulk download
• API Access: Full RESTful API
• SAT AI Search: Unlimited
• Support: Priority email
• Trial: 30 days
• Ideal for: Medium businesses and accountants

​

ENTERPRISE Plan

• Cost: $1,499 MXN/month or$14,999 MXN/year (save 17%)
• Profiles: Unlimited
• Invoices/Expenses: Unlimited
• Reports: Advanced with all exports
• Public Reports: Unlimited tokens
• SAT Download: FIEL/e.firma bulk download
• API Access: Full RESTful API
• Support: Dedicated account manager
• Ideal for: Large enterprises and accounting firms

​

Authentication

Authorization: Bearer YOUR_JWT_TOKEN

​

Getting Current Subscription

curl -X GET https://api.contafy.com/api/subscription \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​

Response

{
  "plan": "PRO",
  "status": "ACTIVE",
  "planPrice": 799,
  "currentPeriodStart": "2024-03-01T00:00:00.000Z",
  "currentPeriodEnd": "2024-04-01T00:00:00.000Z",
  "cancelAtPeriodEnd": false,
  "stripeCustomerId": "cus_XXXXXXXXXX",
  "stripeSubscriptionId": "sub_XXXXXXXXXX",
  "limits": {
    "profiles": 20,
    "invoicesPerMonth": null,
    "expensesPerMonth": null,
    "exportPDF": true,
    "exportExcel": true,
    "reports": "advanced",
    "support": "priority",
    "apiAccess": true
  }
}

​

Viewing Available Plans

​

Public Plans (No Authentication)

curl -X GET "https://api.contafy.com/api/subscription/public-plans?billing=monthly"

​

Query Parameters

​

Response

{
  "plans": [
    {
      "id": "FREE",
      "name": "FREE",
      "price": 0,
      "originalPrice": null,
      "billing": "monthly",
      "limits": {
        "profiles": 1,
        "invoicesPerMonth": null,
        "exportPDF": false,
        "apiAccess": false
      },
      "trialDays": null
    },
    {
      "id": "BASIC",
      "name": "BASIC",
      "price": 299,
      "originalPrice": null,
      "billing": "monthly",
      "limits": {
        "profiles": 5,
        "exportPDF": true,
        "apiAccess": false
      },
      "trialDays": 30
    }
  ],
  "billing": "monthly"
}

​

Creating a Subscription

​

Create Checkout Session

curl -X POST https://api.contafy.com/api/subscription/create-checkout \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "PRO",
    "billing": "annual",
    "promotionCode": "LAUNCH2024"
  }'

​

Request Body

​

Response

{
  "sessionId": "cs_test_xxxxxxxxxxxxx",
  "url": "https://checkout.stripe.com/pay/cs_test_xxxxxxxxxxxxx",
  "message": "Checkout session creada exitosamente"
}

​

Free Trial

• No credit card required upfront
• Full plan features during trial
• Automatic conversion to paid after trial
• One trial per user (tracked by trial_used flag)

{
  "plan": "PRO",
  "status": "TRIALING",
  "currentPeriodEnd": "2024-04-14T00:00:00.000Z"
}

​

Managing Subscriptions

​

Customer Portal

• Update payment methods
• View invoices and receipts
• Change subscription plan
• Cancel subscription

curl -X POST https://api.contafy.com/api/subscription/create-portal-session \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​

Response

{
  "url": "https://billing.stripe.com/session/xxxxxxxxxxxxx",
  "message": "Sesión del portal creada exitosamente"
}

​

Subscription States

​

Active

{
  "status": "ACTIVE",
  "cancelAtPeriodEnd": false
}

​

Trialing

{
  "status": "TRIALING",
  "currentPeriodEnd": "2024-04-14T00:00:00.000Z"
}

​

Past Due

{
  "status": "PAST_DUE"
}

​

Cancelled

{
  "plan": "FREE",
  "status": "ACTIVE",
  "cancelAtPeriodEnd": false
}

​

Upgrading and Downgrading

​

Upgrading

1. Create a new checkout session with the higher plan
2. Complete payment
3. New plan activates immediately
4. Prorated charge for remaining period

​

Downgrading

1. Use Stripe Customer Portal to change plan
2. Current plan remains active until period end
3. New plan activates at next billing cycle
4. Handle profile limits: Freeze excess profiles if downgrading

# Freeze profiles when downgrading
curl -X POST https://api.contafy.com/api/profiles/freeze-others \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "preserveProfileId": "550e8400-e29b-41d4-a716-446655440000",
    "targetPlan": "FREE"
  }'

​

Cancellation

1. Access Customer Portal via /create-portal-session
2. Click “Cancel subscription”
3. Subscription remains active until period end
4. Auto-downgrade to FREE plan

{
  "status": "ACTIVE",
  "cancelAtPeriodEnd": true,
  "currentPeriodEnd": "2024-04-01T00:00:00.000Z"
}

​

Admin Operations

curl -X POST https://api.contafy.com/api/subscription/assign-free \
  -H "Authorization: Bearer ADMIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "plan": "ENTERPRISE"
  }'

​

Webhooks

• checkout.session.completed: Subscription created
• customer.subscription.updated: Plan changed
• customer.subscription.deleted: Subscription cancelled
• invoice.payment_succeeded: Renewal successful
• invoice.payment_failed: Payment failed

​

Promotion Codes

{
  "plan": "PRO",
  "promotionCode": "LAUNCH2024"
}

• Percentage discounts
• Fixed amount discounts
• Extended trial periods

​

Invalid Promotion Code

{
  "error": "Código de descuento inválido",
  "message": "El código de descuento no es válido, ya expiró o no está activo"
}

​

Plan Comparison

​

Best Practices

1. Start with FREE: Test the platform before committing
2. Use trials: Take advantage of 30-day trials on paid plans
3. Choose annual billing: Save 17% with annual subscriptions
4. Monitor usage: Track profile and feature usage via /api/subscription
5. Handle downgrades: Implement profile freezing before plan changes
6. Test webhooks: Set up webhook endpoints before going live
7. Update payment methods: Keep payment methods current to avoid disruptions

​

Common Errors

​

Already Subscribed

{
  "error": "Ya tienes este plan activo",
  "message": "Ya estás suscrito al plan PRO"
}

​

Invalid Plan

{
  "error": "Plan inválido",
  "message": "El plan debe ser BASIC o PRO",
  "allowedPlans": ["BASIC", "PRO"]
}

​

No Active Subscription

{
  "error": "No hay suscripción activa",
  "message": "Debes tener una suscripción activa para acceder al portal de clientes"
}

​

Next Steps

• Set up webhooks to handle subscription events
• Manage profiles within your plan limits
• Review Rate Limits for your plan tier