FastSpring User Management API Guide

Auth method: HTTP Basic Auth (username:password encoded as Base64 in Authorization header; credentials are API credentials set in the FastSpring App Dashboard)

Setup steps

1. Log in to the FastSpring App Dashboard (app.fastspring.com).
2. Navigate to Integrations > API Credentials.
3. Create a new API credential set (username + password).
4. Base64-encode 'username:password' and pass as 'Authorization: Basic ' header on every request.
5. Optionally restrict credentials to specific IP ranges in the dashboard.

List accounts

• Method: GET
• URL: https://api.fastspring.com/accounts
• Watch out for: Returns max 50 accounts per page; use nextPage cursor for subsequent pages.

Request example

GET /accounts?limit=50 HTTP/1.1
Host: api.fastspring.com
Authorization: Basic <base64creds>

Response example

{
  "accounts": [{"id":"abc123","email":"user@example.com"}],
  "nextPage": "cursor_token_here"
}

Get account by ID

• Method: GET
• URL: https://api.fastspring.com/accounts/{account_id}
• Watch out for: Account ID is FastSpring-internal; use lookup endpoint to find by external ID or email.

Request example

GET /accounts/abc123 HTTP/1.1
Host: api.fastspring.com
Authorization: Basic <base64creds>

Response example

{
  "id": "abc123",
  "email": "user@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "subscriptions": ["/subscriptions/sub456"]
}

Get account by email or lookup key

• Method: GET
• URL: https://api.fastspring.com/accounts?email={email}
• Watch out for: Also supports ?lookup.key=value for custom external ID lookups.

Request example

GET /accounts?email=user%40example.com HTTP/1.1
Host: api.fastspring.com
Authorization: Basic <base64creds>

Response example

{
  "accounts": [{"id":"abc123","email":"user@example.com"}]
}

Create account

• Method: POST
• URL: https://api.fastspring.com/accounts
• Watch out for: Email must be unique; creating a duplicate email account returns an error.

Request example

POST /accounts HTTP/1.1
Content-Type: application/json
{
  "email": "newuser@example.com",
  "firstName": "John",
  "lastName": "Smith"
}

Response example

{
  "id": "xyz789",
  "email": "newuser@example.com",
  "url": "/accounts/xyz789"
}

Update account

• Method: POST
• URL: https://api.fastspring.com/accounts/{account_id}
• Watch out for: FastSpring uses POST (not PATCH/PUT) for updates to existing account records.

Request example

POST /accounts/xyz789 HTTP/1.1
Content-Type: application/json
{
  "firstName": "Jonathan",
  "tags": ["vip"]
}

Response example

{
  "id": "xyz789",
  "firstName": "Jonathan",
  "tags": ["vip"]
}

Get account authenticated URL (magic link)

• Method: GET
• URL: https://api.fastspring.com/accounts/{account_id}/authenticate
• Watch out for: Tokens are short-lived; generate immediately before redirecting the user.

Request example

GET /accounts/xyz789/authenticate HTTP/1.1
Host: api.fastspring.com
Authorization: Basic <base64creds>

Response example

{
  "accounts_url": "https://yourstore.onfastspring.com/account?token=..."
}

List subscriptions for account

• Method: GET
• URL: https://api.fastspring.com/subscriptions?accountId={account_id}
• Watch out for: Subscription state values include: active, inactive, canceled, deactivated.

Request example

GET /subscriptions?accountId=xyz789 HTTP/1.1
Host: api.fastspring.com
Authorization: Basic <base64creds>

Response example

{
  "subscriptions": [{"id":"sub456","state":"active","product":"pro-plan"}]
}

Cancel subscription

• Method: DELETE
• URL: https://api.fastspring.com/subscriptions/{subscription_id}
• Watch out for: DELETE cancels at end of billing period by default; use ?billingPeriodEndDate=now to cancel immediately.

Request example

DELETE /subscriptions/sub456 HTTP/1.1
Host: api.fastspring.com
Authorization: Basic <base64creds>

Response example

{
  "subscriptions": [{"id":"sub456","result":"success"}]
}

• Rate limits: FastSpring does not publicly document specific numeric rate limits or per-plan tiers in their developer docs. Requests that exceed undisclosed thresholds may receive HTTP 429 responses.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: No official documentation found for rate-limit headers or Retry-After behavior. Contact FastSpring support for current limits.

• Pagination method: cursor

• Default page size: 50

• Max page size: 50

• Pagination pointer: nextPage (cursor token returned in response body)

• Webhooks available: Yes

• Webhook notes: FastSpring supports webhook notifications (called 'webhooks' or 'event notifications') configured in the App Dashboard under Integrations > Webhooks. Events are sent as HTTP POST to a configured endpoint with a JSON payload. Payloads can be HMAC-SHA256 signed for verification.

• Alternative event strategy: Polling the /accounts and /subscriptions endpoints is an alternative for systems that cannot receive inbound webhooks.

• Webhook events: order.completed, order.failed, subscription.activated, subscription.deactivated, subscription.canceled, subscription.charge.completed, subscription.charge.failed, subscription.payment.overdue, account.created, account.updated, refund.issued

• SCIM available: No
• SCIM version: Not documented
• Plan required: N/A
• Endpoint: Not documented

Limitations:

• FastSpring does not offer a SCIM 2.0 endpoint.
• No native IdP (Okta, Entra ID, Google Workspace, OneLogin) SCIM connector is documented.
• User provisioning must be handled via the REST Accounts API or webhook-driven automation.

Three primary automation scenarios are supported by the API.

First, provisioning a new customer account after an external signup: POST to /accounts with email, firstName, lastName, and a lookup key mapping to your internal user ID;

store the returned FastSpring account id for future operations;

check for an existing account via GET /accounts?email=...

first, since email uniqueness is enforced and duplicates return an error.

Second, redirecting a customer to their self-service portal: retrieve the account ID, call GET /accounts/{account_id}/authenticate to obtain a short-lived magic-link URL, and redirect immediately.

Do not cache this URL - tokens expire quickly and must be generated at redirect time.

Third, deprovisioning by subscription cancellation: look up the account by email, list active subscriptions via GET /subscriptions?accountId={account_id}, then call DELETE /subscriptions/{subscription_id} for each.

By default DELETE cancels at end of billing period;

append ?billingPeriodEndDate=now for immediate cancellation.

Optionally POST a deprovisioned tag to the account record for audit trail purposes.

Provision a new customer account after external signup

1. POST /accounts with email, firstName, lastName, and a lookup key mapping to your internal user ID.
2. Store the returned FastSpring account id alongside your internal user record.
3. Optionally tag the account (e.g., tags: ['trial']) for segmentation.

Watch out for: Email uniqueness is enforced; check for existing accounts via GET /accounts?email=... before creating to avoid duplicate errors.

Redirect a customer to their FastSpring self-service portal

1. Retrieve the customer's FastSpring account ID from your database (or look up via GET /accounts?email=...).
2. Call GET /accounts/{account_id}/authenticate to obtain a short-lived authenticated URL.
3. Redirect the customer's browser to the returned accounts_url immediately.

Watch out for: Tokens expire quickly; do not cache the URL. Generate it at redirect time only.

Deprovision a user by canceling their active subscription

1. Look up the account via GET /accounts?email=... to retrieve the account ID.
2. List subscriptions via GET /subscriptions?accountId={account_id} and identify active subscription IDs.
3. Call DELETE /subscriptions/{subscription_id} for each active subscription.
4. Optionally update the account record via POST /accounts/{account_id} to add a 'deprovisioned' tag for audit purposes.

Watch out for: DELETE cancels at end of billing period by default; append ?billingPeriodEndDate=now for immediate cancellation. Verify subscription state in the response.

The most significant integration trap is the POST-for-updates pattern: FastSpring uses POST to the resource URL for account updates, not PATCH or PUT. Developers expecting standard REST conventions will silently misconfigure update calls.

The API also has no bulk create or update support - each account must be handled individually, which directly affects throughput planning for large-scale identity graph sync operations.

Webhooks configured under Integrations > Webhooks in the App Dashboard are the recommended event-driven alternative to polling. Payloads are HTTP POST with JSON bodies and support HMAC-SHA256 signature verification using a secret set in the dashboard - validation should be treated as mandatory. Key events for identity graph maintenance include account.created, account.updated, subscription.activated, and subscription.deactivated.

For systems that cannot receive inbound webhooks, polling /accounts and /subscriptions is the documented fallback, but the 50-record page cap and undisclosed rate limits make high-frequency polling risky without explicit guidance from FastSpring support.