Loading page…
Connect your store or application to Orphilia. Check stock, look up customer keys, and submit Spotify activations and renewals from your own server.
Start with stock availability. This read shows you how authentication and responses work before you submit an activation.
Contact our team for access. Your credential is tied to your reseller group.
Keep the credential in your server environment and send it in the X-API-Key header.
The stock endpoint returns country rows. Use available_slots to find usable capacity.
curl 'https://orphilia.com/api/v3/re/stocks?save_to_db=false' \
-H "X-API-Key: $ORPHILIA_RESELLER_API_KEY"https://orphilia.com/api/v3/reHTTPSUse an active reseller credential with the required scope. Customer keys must belong to that same reseller group.
| Header | Value | When |
|---|---|---|
X-API-Key | YOUR_RESELLER_API_KEY | Every data or action request |
Content-Type | application/json | Requests with a JSON body |
Run integrations on your server. Keep API keys and Spotify sessions out of browser code, URLs, analytics and public logs. Website sign-in cookies do not authenticate this API.
Each endpoint below shows the fields to send and examples of the response you can receive.
/api/v3/re/stocksFind out which countries have room for new activations. Use available_slots to show what customers can actually select.
country_codestringOptionalmin_slots / max_slotsintegerOptionalsave_to_dbboolean stringOptionalcurl 'https://orphilia.com/api/v3/re/stocks?save_to_db=false' \
-H "X-API-Key: $ORPHILIA_RESELLER_API_KEY"Run this command on your server with your reseller API key.
Illustrative values. Display the status and message returned for the customer’s request.
/api/v3/re/keyInfoCheck whether a key is unused, being processed, or linked to an account. This is also how you follow up after activation or renewal.
orphkeystringRequired{
"orphkey": "YOUR_CUSTOMER_KEY"
}Use POST to keep the customer key out of URLs.
Illustrative values. Display the status and message returned for the customer’s request.
/api/v3/re/upgradeSubmit a Spotify activation using a customer key and the account’s current session cookie. Choose a country with available slots, or use ANY.
orphkeystringRequiredsp_dcstringRequiredcountrystringRequired{
"orphkey": "YOUR_CUSTOMER_KEY",
"sp_dc": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
"country": "US"
}Send JSON with your API key in the X-API-Key header.
Illustrative values. Display the status and message returned for the customer’s request.
/api/v3/re/renewRenew the current account with its session cookie. You can also create a new account during renewal or ask the service to verify a banned account. Choose the request example for your case.
orphkeystringRequiredsp_dcstringCurrent accountnewEmail + passwordstringNew accountcheck_bannedbooleanBanned accountcountrystringOptional{
"orphkey": "YOUR_CUSTOMER_KEY",
"sp_dc": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
}Use the current account’s session cookie. Country is optional.
Illustrative values. Display the status and message returned for the customer’s request.
Read both the HTTP status and the JSON status and message. A request can be rejected even when HTTP is 200.
| Response status | Meaning | What to do |
|---|---|---|
success | Request accepted | For activation or renewal, follow up with keyInfo to confirm the later result. |
in_queue / upgrade_processing / renew_processing | Still processing | Wait and check keyInfo. Do not submit another activation or renewal. |
failed + none + used: 0 | Unused key | For key info, this combination is valid. The key is ready for activation. |
failed_upgrade / failed_renew + bad_cookie | Cookie rejected | Ask for a fresh session cookie. |
success_renew | Key renewed | A confirmed banned-account check makes the key available for activation again. |
failed_renew + account still available | No renewal performed | The account exists. The ban check completed and the key is unchanged. |
not_exist / error | Read the message | The key was not found or the request was rejected. Show the service’s message. |
Responses contain safe service fields with no added branding or credential metadata. Optional fields appear only when returned. The examples use illustrative values; your application should display the actual returned message.
Keep reads paced and give activation and renewal time to finish.
Per reseller credential
Per reseller credential
A shared limit of 120 requests per IP per minute also applies. Service quotas may further limit stock to 1000 reads, key info to 2000 lookups, and activation and renewal to 500 requests each per hour per upstream API key. Wait at least five seconds between lookups of the same key.
On HTTP 429, wait the seconds supplied by Retry-After and retry_after. After a timeout or interruption, check keyInfo before submitting again. There is no client idempotency key, so automatically replaying an uncertain mutation can duplicate it.
Server-side examples for reading stock and submitting an activation. Replace placeholders privately and handle HTTP errors before retrying.
// Server-side JavaScript only. Never embed credentials in browser code.
// Get stock availability
fetch('https://orphilia.com/api/v3/re/stocks', {
headers: { 'X-API-Key': process.env.ORPHILIA_RESELLER_API_KEY }
})
.then(r => r.json())
.then(console.log);
// Upgrade an account
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: 'your-key-here',
sp_dc: process.env.SPOTIFY_SP_DC,
country: 'US'
})
})
.then(r => r.json())
.then(console.log);import os
import requests
headers = { 'X-API-Key': os.environ['ORPHILIA_RESELLER_API_KEY'] }
# Stock availability
r = requests.get(
'https://orphilia.com/api/v3/re/stocks',
headers=headers
)
print(r.json())
# Upgrade
r = requests.post(
'https://orphilia.com/api/v3/re/upgrade',
headers={ **headers, 'Content-Type': 'application/json' },
json={
'orphkey': 'your-key-here',
'sp_dc': os.environ['SPOTIFY_SP_DC'],
'country': 'US'
}
)
print(r.json())<?php
// Stock availability
$ch = curl_init('https://orphilia.com/api/v3/re/stocks');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'X-API-Key: ' . getenv('ORPHILIA_RESELLER_API_KEY') ]);
$stocks = json_decode(curl_exec($ch), true);
curl_close($ch);
// Upgrade
$ch = curl_init('https://orphilia.com/api/v3/re/upgrade');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'orphkey' => 'your-key-here',
'sp_dc' => getenv('SPOTIFY_SP_DC'),
'country' => 'US'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'X-API-Key: ' . getenv('ORPHILIA_RESELLER_API_KEY'),
'Content-Type: application/json'
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
?>// Node.js CommonJS (.cjs), on your server.
const axios = require('axios');
// Stock availability
axios.get(
'https://orphilia.com/api/v3/re/stocks',
{ headers: { 'X-API-Key': process.env.ORPHILIA_RESELLER_API_KEY } }
).then(r => console.log(r.data));
// Upgrade
axios.post(
'https://orphilia.com/api/v3/re/upgrade',
{
orphkey: 'your-key-here',
sp_dc: process.env.SPOTIFY_SP_DC,
country: 'US'
},
{
headers: {
'X-API-Key': process.env.ORPHILIA_RESELLER_API_KEY,
'Content-Type': 'application/json'
}
}
).then(r => console.log(r.data));Choose the customer-facing key format for your store. The API always accepts that customer key as orphkey.
ORPH-XXXX-XXXX-… or ORPHILIA-XXXX-… Recognizable Orphilia prefixes that identify the key as ours.
XXXX-XXXX-XXXX-… or YOURBRAND-XXXX-… Custom formats and optional prefixes for a seamless experience under your own brand.
Need a particular prefix or segment length? Request a custom format
Contact our team for reseller API access or help with your integration.
Building on the API? Other devs hang out in #api-and-developers on Slack or #api-and-developers on Discord. Direct line to Orphilia engineering.