/accounts

Last modified November 3, 2016

Customer Accounts

Use this endpoint to create, update, or get information on FastSpring customer accounts created by the vendor or FastSpring.  All API endpoints work with customer accounts which are represented by unique identifiers. Those identifiers can be obtained by subscribing to Webhooks or by requesting all accounts using GET /accounts. 

You can read more about customer accounts at Customer Information, Accounts and single sign-on.

Get one account

GET /accounts/{id1}

Response Example
{
  "accounts": [
    {
      "action": "account.get",
      "result": "success",
      "account": "wjnkDBJnRcGiOB4Q-3AN9w",
      "contact": {
        "first": "String",
        "last": "String",
        "email": "String",
        "company": "String" or null,
        "phone": "String" or null
      },
      "language": "en" or null,
      "country": "US" or null,
      "lookup": {
        "global": "K1gb96tBS_yMMLZqKdLXCg",
        "custom": "customKey" //optional
      },
      "payment": {
        "methods": 2,
        "active": 2
      },
      "url": "https://store.fastspring.com/storefront/account/K1gb96tBS_yMMLZqKdLXCg",
      "orders": ["orderId", ...],
      "subscriptions": ["subscriptionId", ...],
      "charges": [
        {
          "currency": "USD",
          "total": 10.0,
          "payoutCurrency": "USD",
          "totalInPayoutCurrency": 10.0,
          "status": "successful",
          "order": "6L9YSZ8kRoaFD6DMzVS80Q",
          "orderReference": "COM151120-4954-44172",
          "subscription": null,
          "timestamp": 1448047102396
        }
      ]
    }
  ]
}
 
// Possible error responses
 
{  
   "action":"account.get",
   "account":"wjnkDBJnRcGiOB4Q-3AN9",
   "result":"error",
   "error":{
      "account":"account not found"
   }
}

Get all accounts

GET /accounts/

Response Example
{ 
  "action": "account.getall",
  "result": "success",
  "accounts" : [
    "account-id-1",
    "account-id-2",
    ...
  ] 
}

Create an account

POST /accounts

Request Example
{  
   "contact":{  
      "first":"String",
      "last":"String",      
      "email":"String",
      "company":"String",       //optional
      "phone":"String"         //optional
   },
   "language":"en",             //ISO valid language code
   "country":"US",              //ISO valid country code
   "lookup":{                     //optional
      "custom":"customKey"      //a-zA-Z0-9_- String with length greater than or equal to 4
   }
}
Response Example
// Succesful response
{
   "account":"wjnkDBJnRcGiOB4Q-3AN9w",
   "action":"account.create",
   "result":"success"
}
 
// Possible errors
{  
   "action":"account.create",
   "result":"error",
   "error":{  
      "first":"first is required",  
      "first":"first invalid",                              //the length must be at least 1             
      "last":"last is required",
      "last":"last invalid",                                //the length must be at least 1             
      "email":"email is required",
      "email":"email invalid",                              //valid email format, user@domain.com
      "email":"email already exists, /accounts/id",         //should update the existing account rather than creating one   
      "custom":"custom already exists, /accounts/id",       //should update the existing account rather than creating one   
      "custom":"custom invalid",                            //a-zA-Z0-9_- String with length bigger than or equals to 4
      "country":"country is required",                  
      "country":"country invalid",                          //needs to be an ISO valid country code
      "language":"language is required",
      "language":"language invalid"                         //needs to be an ISO valid language code
   }
}

Update existing account

POST /accounts/{id}

Request Example
{  
   "contact":{  
      "first":"String",
      "last":"String"
      "email":"String",
      "company":"String",       
      "phone":"String",         
   },
   "language":"en",             //ISO valid language code
   "country":"US",              //ISO valid country code
   "lookup":{                     
      "custom":"customKey"      //a-zA-Z0-9_- String with length bigger than or equals to 4
   }
}
Response Example
// Successful response
{
   "account":"wjnkDBJnRcGiOB4Q-3AN9w",
   "action":"account.update",
   "result":"success"
}
 
// Possible errors
{  
   "action":"account.create",
   "result":"error",
   "error":{  
      "first":"first invalid",                              //the length must be at least 1 
      "last":"last invalid",                                //the length must be at least 1 
      "email":"email invalid",                              //valid email format, user@domain.com
      "email":"email already exists /accounts/id",          //should update the existing account rather than creating one   
      "custom":"custom already exists /accounts/id",        //should update the existing account rather than creating one   
      "custom":"custom invalid",                            //a-zA-Z0-9_- String with length bigger than or equals to 4
      "country":"country invalid",                          //needs to be an ISO valid country code
      "language":"language invalid"                         //needs to be an ISO valid language code
   }
}

Lookup accounts by parameters

GET /accounts?key=value&limit=15&page=2&begin=2015-01-01&end=2015-12-31

Supported keys and their values:

Key Value
email
Account email
custom Account custom key
global Account global key
orderId Order id
orderReference Order Reference
subscriptionId Subscription ID
products Product ID
subscriptions "active", "ended", "canceled", "started" will return accounts with subscriptions in the corresponding state
refunds true
Response Example
// Successful response
{  
   "action":"account.lookup",
   "result":"success",
   "accounts":[
      {  
         "account":"wjnkDBJnRcGiOB4Q-3AN9w",
         ...
         // full account object
      },
      ...
   ]
}
 
// Possible errors
{  
   "action":"account.lookup",
   "result":"error",
   "error":{
      "key":"Unrecognized Key",
      "subscriptions":"Supported value: active, ended, canceled, started",
      "refunds":"Supported value: true",
      "begin":"Invalid begin date",
      "end":"Invalid end date",
      "end":"End date myst be after begin date",
      "AnotherKey":"Only one condition can be specified"
   }
}

Get authenticated account management URL

Returns authenticated url valid for an hour.

GET /accounts/{id1}[,{id2},{id3},...]/authenticate

Response Example
{  
   "accounts":[  
      // Successful response
      {  
         "action":"account.authenticate.get",
         "result":"success",
         "account":"YgfM1IwpR4qQItQU5SfFMA",
         "url":"https://company.onfastspring.com/account/50HsQS1-QcOR3dzEF_rm3w/ydYUZOVrQ24"
      },
      // Failed
      {  
         "action":"account.authenticate.get",         
         "account":"123"
         "result":"error",
         "error": {
           "account": "Not found"
         }
      }
   ]
}