/accounts

Last modified September 18, 2017

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"                                     // account ID specified could not be found
   }
}

Get all accounts

GET /accounts/

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

Create an account

Caution

When creating an account, be sure to include the customer's country.  This information is required for certain non-credit card payment methods (e.g. PayPal), and some transactions (e.g. those using sessions generated via the /sessions endpoint) could potentially fail if the country is not included in the customer's 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
   }
}

Look up accounts by parameters


GET /accounts?key=value&limit=15&page=2

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
limit Integer value indicating the maximum number of records to be returned
Or, when used together with page, maximum number of records to be returned per page
page Integer value that must be used in conjunction with limit to specify which page of results should be returned
Response Example
// Successful response
{  
   "action":"account.lookup",
   "result":"success",
   "accounts":[
      {  
         "account":"wjnkDBJnRcGiOB4Q-3AN9w",
         ...
         // full account object
      },
      ...
   ]
}
 
// Possible errors
{  
   "action":"account.lookup",
   "result":"error",
   "error":{
      "custom":"Account not found",
      "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"
         }
      }
   ]
}