Connect your platform

A server-side guide to availability, customer key checks, upgrades and renewals.

01 · Keep access on your server

Base URL: https://orphilia.com/api/v3/re. Send an issued reseller credential in the X-API-Key header. Ask our team to arrange access; credentials are shown once and can be revoked or replaced.

The credential must be active, scoped for the requested operation and bound to your reseller group. Its format alone does not grant access. Customer keys must belong to that same group. Original provider keys are never required.

Store the credential in your server’s secret environment. Keep API credentials, customer keys, passwords and Spotify sessions out of frontend bundles, URLs, analytics and logs. Orphilia browser cookies and partner login tokens do not authorize this API.

Read stock · terminal on your server

curl --fail-with-body 'https://orphilia.com/api/v3/re/stocks?save_to_db=false' \
  -H "X-API-Key: $ORPHILIA_RESELLER_API_KEY"

Stock lists save a snapshot by default. Use save_to_db=false for reads that should not record one. Availability can change before an activation is submitted.

02 · Available endpoints

Paths below are relative to the base URL. Data and action routes require the reseller credential; the two GET instruction routes are informational.

GET/stocks: Current country stock; optional country_code, min_slots, max_slots and save_to_db filters.
GET/stocks/country/{countryCode}: One two-letter country code; 404 if absent from the report.
GET/stocks/stats: Current totals, average slots and top/bottom five countries.
POST/keyInfo: Inspect a customer alias using a JSON body. Preferred over a URL query.
GET/keyInfo?orphkey=…: Compatibility lookup; URLs may be logged. Prefer POST.
POST/upgrade: Submit an activation with customer credentials and a country.
POST/renew: Submit a renewal with customer credentials.
GET/upgrade: Request instructions only. Does not submit an activation.
GET/renew: Request instructions only. Does not submit a renewal.

Download reseller OpenAPI

03 · Send a customer request

Inspect a customer key · POST recommended

curl --fail-with-body 'https://orphilia.com/api/v3/re/keyInfo' \
  -H "X-API-Key: $ORPHILIA_RESELLER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"orphkey":"YOUR_CUSTOMER_KEY"}'

For upgrade and renewal, send orphkey and either sp_dc (the sp_doc alias is supported) or both login and password. Session codes accept 50–300 characters from letters, digits, underscore, equals and hyphen. Passwords accept 6–256 characters. Omit unused fields instead of sending empty strings.

Upgrade also requires a two-letter country from current availability. Customer aliases accept 4–4096 characters without whitespace. Login accepts up to 254 characters. An optional renewal email change uses newEmail or newemail (up to 254 characters), and requires a password.

Submit upgrade · server-side JavaScript

// Server-side JavaScript. Do not put these secrets in browser code.
const response = await fetch('https://orphilia.com/api/v3/re/upgrade', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORPHILIA_RESELLER_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    orphkey: customerKey, // An alias from your assigned reseller group
    sp_dc: spotifySession, // Customer-provided, 50–300 characters
    country: 'US' // Choose from current availability
  }),
  signal: AbortSignal.timeout(25000)
});
const result = await response.json();
// Inspect response.ok AND result.status. A timeout is an uncertain outcome.
// Reconcile keyInfo or contact support before resubmitting.

Renewal JSON body · POST /renew

{
  "orphkey": "YOUR_CUSTOMER_KEY",
  "sp_dc": "YOUR_CUSTOMER_PROVIDED_SPOTIFY_SESSION"
}

The displayed session value is a placeholder. Supply the customer’s complete session privately on your server.

04 · Handle the outcome

Compatibility responses are returned directly, without an extra native data wrapper. Stock returns success, timestamp and a data array of country, country_code and slots. Country reads return one data object; stats return a statistics object. Key info returns fields including orphkey, status, boolean used and nullable username/date details. Reseller responses include safe credential metadata.

Upgrade and renewal return status and message. HTTP 200 alone does not confirm completion. Treat queued, pending, unknown, interrupted and timeout outcomes as uncertain; check keyInfo or ask support before submitting again. There is no client idempotency key for these mutations.

Errors include success: false, status: "error", message and a support reference. Handle 400 invalid input, 401 missing, invalid or revoked credentials or disabled groups, 403 missing scopes or a blocked browser origin, 404 missing or out-of-group keys, 409 busy keys, 422 rejected requests, 429 rate limits and 502/503 unavailable integrations.

Each credential is limited to 60 stock reads or 20 service requests per minute; a shared 120-request IP limit also applies. On 429, respect Retry-After. Use bounded backoff for reads. Never automatically replay an uncertain activation or renewal.

View queue status · Reseller overview · Integration help

Loading page…

// Server-side JavaScript. Do not put these secrets in browser code. const response = await fetch('https://orphilia.com/api/v3/re/upgrade', { method: 'POST', headers: { 'X-API-Key': process.env.ORPHILIA_RESELLER_API_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ orphkey: customerKey, // An alias from your assigned reseller group sp_dc: spotifySession, // Customer-provided, 50–300 characters country: 'US' // Choose from current availability }), signal: AbortSignal.timeout(25000) }); const result = await response.json(); // Inspect response.ok AND result.status. A timeout is an uncertain outcome. // Reconcile keyInfo or contact support before resubmitting.