Creating a subscription
Once you have a created company, added a user to the company, and created a payment instrument for that user, you can create a subscription for that user. To do so, you will need the unique company identifier returned in the create company response and the unique user identifier returned in the create user response. Note that you do not need the unique identifier for the payment instrument, but the user must have a valid payment instrument in the database. The unique identifier for your new subscription will be returned in the response (shown in the example below). This identifier will be used in calls to manage the subscription.
URL endpoint: /api/billing/v1/companies/{companyId}/users/{userId}/subscriptions
Method: POST
Parameters:
- companyId - The unique identifier for the company provided by the channel. This id can be obtained either from the response returned when the company is created via the API, or by using the API to list the companies in order to view the id for your company.
- userId - The unique identifier for the user provided by the channel. This id can be obtained either from the response returned when the user is created via the API, or by using the API to list the users for the company in order to view the id for the user.
- A valid JSON or XML object with subscription data
HTTP status codes
| HTTP Status Code | Description |
|---|---|
| 201 Created | The subscription was created. |
| 400 Bad Request | Some required fields were not received. |
| 404 Not Found | The specified company or user was not found. |
| 409 Conflict | A subscription already exists for the specified company. You may assign the user to the existing subscription or change the subscription (to a different edition, or upgrade/downgrade modifiable options). |
Below is an example of a basic subscription creation request and response. Additional examples are provided in the example section of this document.
Request
- JSON
POST https://www.appdirect.com/api/billing/v1/companies/a012bb88-c2c5-40a1-b140-ec6ed4593b78/users/3d4d2342-b7c4-4865-85bd-842f269adae6/subscriptions
Host: www.appdirect.com
Authorization OAuth oauth_version="1.0", oauth_signature_method="HMAC-SHA1", oauth_nonce="VeJO1tP7RKUE1rz", oauth_timestamp="1438728054", oauth_consumer_key="appdirect-91", oauth_signature="xy37tmDbpwuIHZJIioRSB3GGAhM%3D"
Content-Type application/json
{
"order": {
"paymentPlanId": "541",
"orderLines":[ {
"unit": "USER",
"quantity": "3"
}]
}
}
- XML
POST https://www.appdirect.com/api/billing/v1/companies/a012bb88-c2c5-40a1-b140-ec6ed4593b78/users/3d4d2342-b7c4-4865-85bd-842f269adae6/subscriptions
Host: www.appdirect.com
Authorization OAuth oauth_version="1.0", oauth_signature_method="HMAC-SHA1", oauth_nonce="VeJO1tP7RKUE1rz", oauth_timestamp="1438728054", oauth_consumer_key="appdirect-91", oauth_signature="xy37tmDbpwuIHZJIioRSB3GGAhM%3D"
Content-Type application/xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<subscription>
<order>
<paymentPlanId>541</paymentPlanId>
<orderLines>
<orderLine>
<unit>>USER</unit>
<quantity>3</quantity>
</orderLine>
</orderLines>
</order>
</subscription>;
Response
- JSON
Status Code: 201 Created
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Content-Encoding: gzip
Content-Length: 1272
Content-Type: application/json;charset=UTF-8
Date: Wed, 12 Aug 2015 19:43:28 GMT
Expires: 0
Pragma: no-cache
Server: Apache-Coyote/1.1
Vary: Accept-Encoding
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
x-content-type-options: nosniff
{
"id": "2baa78aa-c5a8-49e8-b49f-ec5e8fe58086",
"creationDate": "2015-08-12T13:43:26-06:00",
"externalAccountId": "8dcdc107-ab42-43de-b772-d9f2a06d58fc",
"status": "ACTIVE",
"maxUsers": "4",
"order": {
"id": "1587",
"startDate": "2015-08-12T00:00:00-06:00",
"nextBillingDate": "2015-09-01T00:00:00-06:00",
"status": "ACTIVE",
"frequency": "MONTHLY",
"currency": "USD",
"type": "NEW",
"totalPrice": "26.5700000000",
"user": {
"-id": "3d4d2342-b7c4-4865-85bd-842f269adae6",
"-href": "https://www.appdirect.com/api/account/v1//users/3d4d2342-b7c4-4865-85bd-842f269adae6"
},
"company": {
"-id": "a012bb88-c2c5-40a1-b140-ec6ed4593b78",
"-href": "https://www.appdirect.com/api/account/v1//companies/a012bb88-c2c5-40a1-b140-ec6ed4593b78"
},
"paymentPlan": {
"-href": "https://www.appdirect.com/api/marketplace/v1/products/78/editions/440/paymentPlans/541",
"id": "541",
"uuid": "dcdf76e8-e7d2-4fe3-bc12-f6d03bb4c8b0",
"frequency": "MONTHLY",
"contract": {
"blockContractDowngrades": "false",
"blockContractUpgrades": "false",
"blockSwitchToShorterContract": "false"
},
"allowCustomUsage": "false",
"keepBillDateOnUsageChange": "false",
"separatePrepaid": "false",
"isPrimaryPrice": "false",
"costs": {
"cost": [
{
"unit": "NOT_APPLICABLE",
"minUnits": "0.0000000000",
"meteredUsage": "false",
"increment": "1.0000000000",
"pricePerIncrement": "false",
"blockContractDecrease": "false",
"blockContractIncrease": "false",
"blockOriginalContractDecrease": "false",
"amount": {
"CAD": "10",
"CHF": "10",
"SEK": "10",
"USD": "10"
}
},
{
"unit": "ONE_TIME_SETUP",
"minUnits": "0.0000000000",
"meteredUsage": "false",
"increment": "1.0000000000",
"pricePerIncrement": "false",
"blockContractDecrease": "false",
"blockContractIncrease": "false",
"blockOriginalContractDecrease": "false",
"amount": {
"CAD": "1.5",
"CHF": "1.5",
"SEK": "1.5",
"USD": "1.5"
}
},
{
"unit": "USER",
"minUnits": "0.0000000000",
"meteredUsage": "false",
"pricePerIncrement": "false",
"blockContractDecrease": "false",
"blockContractIncrease": "false",
"blockOriginalContractDecrease": "false",
"amount": {
"CAD": "5",
"CHF": "5",
"SEK": "5",
"USD": "5"
}
},
{
"unit": "ONE_TIME_SETUP",
"unitDependency": "USER",
"minUnits": "0.0000000000",
"meteredUsage": "false",
"increment": "1.0000000000",
"pricePerIncrement": "false",
"blockContractDecrease": "false",
"blockContractIncrease": "false",
"blockOriginalContractDecrease": "false",
"amount": {
"CAD": "2",
"CHF": "2",
"SEK": "2",
"USD": "2"
}
}
]
}
},
"paymentPlanId": "541",
"activated": "false",
"oneTimeOrders": {
"oneTimeOrder": {
"id": "1586",
"startDate": "2015-08-12T00:00:00-06:00",
"endDate": "2015-08-12T00:00:00-06:00",
"nextBillingDate": "2015-08-12T13:43:27-06:00",
"status": "ONE_TIME",
"frequency": "ONE_TIME",
"currency": "USD",
"type": "ONE_TIME_FEE",
"totalPrice": "7.9700000000",
"paymentPlan": {
"-id": "541",
"-href": "https://www.appdirect.com/api/marketplace/v1/products/78/editions/440/paymentPlans/541"
}
}
},
"orderLines": {
"orderLine": [
{
"description": "LATEST AUTO_WEBAPP_NEW - Recurring edition all fees except contract - Monthly Fee",
"id": "2435",
"price": "10.0000000000",
"quantity": "1.0000000000",
"totalPrice": "10.0000000000",
"type": "ITEM",
"unit": "NOT_APPLICABLE"
},
{
"description": "LATEST AUTO_WEBAPP_NEW - Recurring edition all fees except contract - Per User Fee",
"id": "2436",
"price": "5.0000000000",
"quantity": "3.0000000000",
"totalPrice": "15.0000000000",
"type": "ITEM",
"unit": "USER"
},
{
"description": "Sales Tax",
"id": "2437",
"percentage": "6.2800000000",
"quantity": "1.0000000000",
"totalPrice": "1.5700000000",
"type": "TAX"
}
]
},
"user": {
"-id": "3d4d2342-b7c4-4865-85bd-842f269adae6",
"-href": "https://www.appdirect.com/api/account/v1//users/3d4d2342-b7c4-4865-85bd-842f269adae6"
},
"company": {
"-id": "a012bb88-c2c5-40a1-b140-ec6ed4593b78",
"-href": "https://www.appdirect.com/api/account/v1//companies/a012bb88-c2c5-40a1-b140-ec6ed4593b78"
},
"product": {
"-id": "78",
"-href": "https://www.appdirect.com/api/marketplace/v1/products/78"
},
"edition": {
"-id": "440",
"-href": "https://www.appdirect.com/api/marketplace/v1/products/78/editions/440"
}
}
- XML
Status Code: 201 Created
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Content-Encoding: gzip
Content-Length: 1272
Content-Type: application/xml;charset=UTF-8
Date: Wed, 12 Aug 2015 19:43:28 GMT
Expires: 0
Pragma: no-cache
Server: Apache-Coyote/1.1
Vary: Accept-Encoding
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
x-content-type-options: nosniff
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<subscription xmlns:atom="http://www.w3.org/2005/Atom">
<id>2baa78aa-c5a8-49e8-b49f-ec5e8fe58086</id>
<creationDate>2015-08-12T13:43:26-06:00</creationDate>
<externalAccountId>8dcdc107-ab42-43de-b772-d9f2a06d58fc</externalAccountId>
<status>ACTIVE</status>
<maxUsers>4</maxUsers>
<order>
<id>1587</id>
<startDate>2015-08-12T00:00:00-06:00</startDate>
<nextBillingDate>2015-09-01T00:00:00-06:00</nextBillingDate>
<status>ACTIVE</status>
<frequency>MONTHLY</frequency>
<currency>USD</currency>
<type>NEW</type>
<totalPrice>26.5700000000</totalPrice>
<user id="3d4d2342-b7c4-4865-85bd-842f269adae6" href="https://www.appdirect.com/api/account/v1//users/3d4d2342-b7c4-4865-85bd-842f269adae6"/>
<company id="a012bb88-c2c5-40a1-b140-ec6ed4593b78" href="https://www.appdirect.com/api/account/v1//companies/a012bb88-c2c5-40a1-b140-ec6ed4593b78"/>
<paymentPlan href="https://www.appdirect.com/api/marketplace/v1/products/78/editions/440/paymentPlans/541">
<id>541</id>
<uuid>dcdf76e8-e7d2-4fe3-bc12-f6d03bb4c8b0</uuid>
<frequency>MONTHLY</frequency>
<contract>
<blockContractDowngrades>false</blockContractDowngrades>
<blockContractUpgrades>false</blockContractUpgrades>
<blockSwitchToShorterContract>false</blockSwitchToShorterContract>
</contract>
<allowCustomUsage>false</allowCustomUsage>
<keepBillDateOnUsageChange>false</keepBillDateOnUsageChange>
<separatePrepaid>false</separatePrepaid>
<isPrimaryPrice>false</isPrimaryPrice>
<costs>
<cost>
<unit>NOT_APPLICABLE</unit>
<minUnits>0.0000000000</minUnits>
<meteredUsage>false</meteredUsage>
<increment>1.0000000000</increment>
<pricePerIncrement>false</pricePerIncrement>
<blockContractDecrease>false</blockContractDecrease>
<blockContractIncrease>false</blockContractIncrease>
<blockOriginalContractDecrease>false</blockOriginalContractDecrease>
<amount>
<CAD>10</CAD>
<CHF>10</CHF>
<SEK>10</SEK>
<USD>10</USD>
</amount>
</cost>
<cost>
<unit>ONE_TIME_SETUP</unit>
<minUnits>0.0000000000</minUnits>
<meteredUsage>false</meteredUsage>
<increment>1.0000000000</increment>
<pricePerIncrement>false</pricePerIncrement>
<blockContractDecrease>false</blockContractDecrease>
<blockContractIncrease>false</blockContractIncrease>
<blockOriginalContractDecrease>false</blockOriginalContractDecrease>
<amount>
<CAD>2</CAD>
<CHF>2</CHF>
<SEK>2</SEK>
<USD>2</USD>
</amount>
</cost>
</costs>
</paymentPlan>
<paymentPlanId>541</paymentPlanId>
<activated>false</activated>
<oneTimeOrders>
<oneTimeOrder>
<id>1586</id>
<startDate>2015-08-12T00:00:00-06:00</startDate>
<endDate>2015-08-12T00:00:00-06:00</endDate>
<nextBillingDate>2015-08-12T13:43:27-06:00</nextBillingDate>
<status>ONE_TIME</status>
<frequency>ONE_TIME</frequency>
<currency>USD</currency>
<type>ONE_TIME_FEE</type>
<totalPrice>7.9700000000</totalPrice>
<paymentPlan id="541" href="https://www.appdirect.com/api/marketplace/v1/products/78/editions/440/paymentPlans/541"/>
</oneTimeOrder>
</oneTimeOrders>
<orderLines>
<orderLine>
<description>LATEST AUTO_WEBAPP_NEW - Recurring edition all fees except contract - Monthly Fee</description>
<id>2435</id>
<price>10.0000000000</price>
<quantity>1.0000000000</quantity>
<totalPrice>10.0000000000</totalPrice>
<type>ITEM</type>
<unit>NOT_APPLICABLE</unit>
</orderLine>
<orderLine>
<description>LATEST AUTO_WEBAPP_NEW - Recurring edition all fees except contract - Per User Fee</description>
<id>2436</id>
<price>5.0000000000</price>
<quantity>3.0000000000</quantity>
<totalPrice>15.0000000000</totalPrice>
<type>ITEM</type>
<unit>USER</unit>
</orderLine>
<orderLine>
<description>Sales Tax</description>
<id>2437</id>
<percentage>6.2800000000</percentage>
<quantity>1.0000000000</quantity>
<totalPrice>1.5700000000</totalPrice>
<type>TAX</type>
</orderLine>
</orderLines>
<parameters/>
</order>
<user id="3d4d2342-b7c4-4865-85bd-842f269adae6" href="https://www.appdirect.com/api/account/v1//users/3d4d2342-b7c4-4865-85bd-842f269adae6"/>
<company id="a012bb88-c2c5-40a1-b140-ec6ed4593b78" href="https://www.appdirect.com/api/account/v1//companies/a012bb88-c2c5-40a1-b140-ec6ed4593b78"/>
<product id="78" href="https://www.appdirect.com/api/marketplace/v1/products/78"/>
<edition id="440" href="https://www.appdirect.com/api/marketplace/v1/products/78/editions/440"/>
</subscription>
Was this page helpful?
Tell us more…
Help us improve our content. Responses are anonymous.
Thanks
We appreciate your feedback!