Skip to main content

​
REST API

Subscribd ships a public REST API for headless or mobile integrations. It is disabled by default — enable it in config/subscribd.php: 
'api' => [
    'enabled'          => true,
    'prefix'           => 'subscribd/v1',
    'token_middleware' => ['auth'],
],

​
Authentication

The API uses stateless Bearer tokens issued per-billable. The token issuance and revocation endpoints are protected by your own session auth (the token_middleware config key).

​
Issue a token

POST /subscribd/v1/tokens
No request body required. The authenticated user receives a token scoped to their account. Response: 
{
  "token": "sbst_abc123...",
  "createdAt": "2026-04-19T10:00:00Z"
}

​
Revoke a token

DELETE /subscribd/v1/tokens/{token}
Use the Bearer token on all other endpoints: 
Authorization: Bearer sbst_abc123...

​
Plans

Plans are read-only via the API. Write operations (create/update/delete) are admin-only.

​
List plans

GET /subscribd/v1/plans
Response: 
{
  "data": [
    {
      "id": 1,
      "key": "pro",
      "name": "Pro",
      "price": 4900,
      "currency": "USD",
      "interval": "month",
      "intervalCount": 1,
      "trialDays": 14,
      "isRecurring": true,
      "features": {
        "exports": true
      },
      "items": [
        {
          "key": "projects",
          "name": "Projects",
          "includedQuantity": 3,
          "unitPrice": 1000,
          "capBehavior": "charge_until_ceiling",
          "ceiling": 50
        }
      ]
    }
  ]
}

​
Get a plan

GET /subscribd/v1/plans/{plan}

​
Subscriptions

All subscription endpoints are scoped to the token owner — a billable cannot access another billable’s subscriptions.

​
List subscriptions

GET /subscribd/v1/subscriptions
Response: 
{
  "data": [
    {
      "id": 42,
      "name": "default",
      "status": "active",
      "plan": { "key": "pro", "name": "Pro" },
      "currentPeriodStart": "2026-04-01T00:00:00Z",
      "currentPeriodEnd":   "2026-05-01T00:00:00Z",
      "trialEndsAt": null,
      "canceledAt": null,
      "endsAt": null,
      "createdAt": "2026-03-01T00:00:00Z"
    }
  ]
}

​
Get a subscription

GET /subscribd/v1/subscriptions/{subscription}

​
Cancel a subscription

POST /subscribd/v1/subscriptions/{subscription}/cancel
Request body (optional): 
{ "immediately": false }
immediately: false (default) cancels at period end (grace period). immediately: true revokes access immediately.

​
Resume a subscription

POST /subscribd/v1/subscriptions/{subscription}/resume
Resumes a paused or grace-period subscription.

​
Tally metered usage

POST /subscribd/v1/subscriptions/{subscription}/tally-usage
Request body: 
{
  "feature": "api_calls",
  "quantity": 150,
  "idempotencyKey": "req_abc123"
}
idempotencyKey is optional. When provided, duplicate requests with the same key are silently ignored.

​
Upgrade from free

POST /subscribd/v1/subscriptions/{subscription}/upgrade-from-free
Request body: 
{ "planKey": "pro" }
Upgrades a community/free subscription to a paid plan. Assumes payment has already been collected.

​
Invoices

​
List invoices

GET /subscribd/v1/invoices
Response: 
{
  "data": [
    {
      "id": 17,
      "status": "paid",
      "total": 4900,
      "currency": "USD",
      "paidAt": "2026-04-01T00:00:00Z",
      "periodStart": "2026-04-01T00:00:00Z",
      "periodEnd": "2026-05-01T00:00:00Z",
      "pdfUrl": "/subscribd/invoices/17/pdf"
    }
  ]
}

​
Get an invoice

GET /subscribd/v1/invoices/{invoice}

​
Payment methods

​
List payment methods

GET /subscribd/v1/payment-methods
Response: 
{
  "data": [
    {
      "id": 5,
      "brand": "visa",
      "last4": "4242",
      "expMonth": 12,
      "expYear": 2028,
      "isDefault": true
    }
  ]
}

​
Delete a payment method

DELETE /subscribd/v1/payment-methods/{paymentMethod}

​
Set as default

POST /subscribd/v1/payment-methods/{paymentMethod}/default

​
Error responses

All errors return a JSON body with message and an appropriate HTTP status code.
StatusMeaning
401Invalid or missing Bearer token
403Token owner does not own the resource
404Resource not found
422Validation error — errors key contains field-level messages
500Gateway or server error — check your logs
{
  "message": "The subscription does not belong to this token owner.",
  "errors": {}
}

​
Rate limiting

Rate limiting is not applied by default. Add it via your token_middleware stack: 
'token_middleware' => ['auth', 'throttle:60,1'],

​
Next steps

  • Testing — How to test API integrations with the FakeGateway
  • Hooks and Events — Events fired during API operations