Skip to main content

Managing Customers

Customers are the users who can access your private packages. Each customer has an access token for Composer authentication.

Creating a Customer​

curl -X POST https://packages.example.com/api/v1/customers \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "email": "dev@acme.com",
    "external_id": "stripe_cus_abc123"
  }'

Response:

{
  "id": "cust_xyz789",
  "name": "Acme Corporation",
  "email": "dev@acme.com",
  "external_id": "stripe_cus_abc123",
  "token": "tok_secret_xyz",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}

Customer Status​

Customers can have the following statuses:

StatusDescriptionPackage Access
activeNormal stateFull access
suspendedTemporarily blocked (e.g., payment failed)No access
frozenLocked to specific versionsLimited access
expiredSubscription endedNo access

Suspend a Customer​

Temporarily block access (e.g., payment failure with grace period):

curl -X POST https://packages.example.com/api/v1/customers/cust_xyz789/suspend \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Payment failed"}'

Reactivate a Customer​

Restore access after payment is resolved:

curl -X POST https://packages.example.com/api/v1/customers/cust_xyz789/reactivate \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Freeze a Customer​

Lock to specific versions (subscription ended, but allow existing installs):

curl -X POST https://packages.example.com/api/v1/customers/cust_xyz789/freeze \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "versions": [
      {"package": "vendor/package", "version": "2.0.0"}
    ]
  }'

Package Access​

Grant access to specific packages:

curl -X POST https://packages.example.com/api/v1/customers/cust_xyz789/packages \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "package": "vendor/package",
    "constraint": "^2.0"
  }'

Version Constraints​

ConstraintDescription
*All versions
^2.0Semver compatible with 2.x
>=1.0 <3.0Range
2.0.0Exact version

Revoke Access​

curl -X DELETE https://packages.example.com/api/v1/customers/cust_xyz789/packages/vendor%2Fpackage \
  -H "Authorization: Bearer $ADMIN_TOKEN"

External IDs​

Use external_id to link customers to your e-commerce or billing system:

# Find customer by Stripe customer ID
curl https://packages.example.com/api/v1/customers/by-external/stripe_cus_abc123 \
  -H "Authorization: Bearer $ADMIN_TOKEN"

This is useful for webhook integrations with Stripe, Paddle, or your custom system.

Next Steps​