Recaudo Docs
Sign up

Payments & customers

Subscriptions

Subscriptions let you charge your customers on a recurring basis. They support trial periods, pauses and plan changes.

POST /v1/subscriptions

Create subscription

Creates a new subscription for a customer. You can use a stored payment method or a recaudo.js token.

Tokenization: You can use the parameter token with a recaudo.js token (tok_xxx) instead of payment_method. The token will be automatically converted into a stored payment method.

Parameters

Parameter Type Required Description
customer string (uuid) Yes Customer ID
plan string (uuid) Yes Subscription plan ID
payment_method string (uuid) No* Stored payment method ID. Required if there is no trial and no token is used.
token string No* recaudo.js token (tok_xxx for Conekta, pm_xxx for Stripe). Alternative to payment_method.
card object No Card info from recaudo.js: { brand, last4, exp_month, exp_year }. Recommended for better tracking
trial_days integer No Trial days (0-365)
amount numeric No Custom amount (overrides the plan)
metadata object No Additional data 
curl -X POST https://recaudo.app/api/v1/subscriptions \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "550e8400-e29b-41d4-a716-446655440000",
    "plan": "660e8400-e29b-41d4-a716-446655440001",
    "token": "tok_abc123def456",
    "card": {
      "brand": "visa",
      "last4": "4242",
      "exp_month": 12,
      "exp_year": 2027
    },
    "metadata": {
      "signup_source": "landing_page"
    }
  }'
curl -X POST https://recaudo.app/api/v1/subscriptions \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "550e8400-e29b-41d4-a716-446655440000",
    "plan": "660e8400-e29b-41d4-a716-446655440001",
    "payment_method": "770e8400-e29b-41d4-a716-446655440002",
    "metadata": {
      "signup_source": "landing_page"
    }
  }'
Response 201 
{
  "id": "2b76a920-5381-4414-a2ae-34950faf16d7",
  "object": "subscription",
  "status": "active",
  "customer_id": "8e250c25-9d84-4892-98ec-d71fc1fcd3c7",
  "plan": {
    "id": "5f1c7b3e-2a94-4d18-b6c0-9e3f8a1d7c25",
    "name": "Premium Mensual",
    "amount": 299.00,
    "currency": "MXN",
    "interval": "month"
  },
  "current_period_start": "2024-01-15T00:00:00Z",
  "current_period_end": "2024-02-15T00:00:00Z",
  "trial_end": null,
  "cancel_at_period_end": false,
  "created_at": "2024-01-15T10:30:00Z"
}

Subscription actions

POST /v1/subscriptions/:id/cancel Cancel subscription 
curl -X POST https://recaudo.app/api/v1/subscriptions/2b76a920-5381-4414-a2ae-34950faf16d7/cancel \
  -H "Authorization: Bearer sk_live_xxx" \
  -d '{"cancel_at_period_end": true, "reason": "too_expensive"}'
POST /v1/subscriptions/:id/pause Pause subscription 
curl -X POST https://recaudo.app/api/v1/subscriptions/2b76a920-5381-4414-a2ae-34950faf16d7/pause \
  -H "Authorization: Bearer sk_live_xxx"
POST /v1/subscriptions/:id/resume Resume subscription 
curl -X POST https://recaudo.app/api/v1/subscriptions/2b76a920-5381-4414-a2ae-34950faf16d7/resume \
  -H "Authorization: Bearer sk_live_xxx"
Was this page helpful? Thanks for letting us know.
Esc