Changing a subscription
Once you have a created valid subscription, you can change the subscription. To do so, you will need the unique company identifier returned in the create company response, the unique user identifier returned in the create user response, and the unique subscription identifer returned in the create subscription 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 identifiers may also be found by calling the respective list API methods.
URL endpoint: /api/billing/v1/companies/{companyId}/users/{userId}/subscriptions/{subscriptionId}
Method: PUT
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.
- subscriptionId - The unique identifier for the subscription provided by the channel. This id can be obtained either from the response returned when the subscription is created via the API, or by using the API to list the subscriptions for the company and user in order to view the id for the subscription.
- 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, user, or subscription was not found. |
| 409 Conflict | A subscription with identical attributes 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 the most basic subscription change request and response. In this case, the edition is simply changed to a new edition. Additional examples are provided in the example section of this document. All of the examples presented assume you have successfully created a subscription as described in Create subscriptions.
Request
- JSON
PUT https://www.appdirect.com/api/billing/v1/companies/a012bb88-c2c5-40a1-b140-ec6ed4593b78/users/3d4d2342-b7c4-4865-85bd-842f269adae6/subscriptions/902ac86e-89c2-4d02-8d2d-614d2117bd2c
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
{
"id": "902ac86e-89c2-4d02-8d2d-614d2117bd2c",
"order": {
"paymentPlanId": "568"
}
}
- XML
PUT https://www.appdirect.com/api/billing/v1/companies/a012bb88-c2c5-40a1-b140-ec6ed4593b78/users/3d4d2342-b7c4-4865-85bd-842f269adae6/subscriptions/902ac86e-89c2-4d02-8d2d-614d2117bd2c
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>
<id>"902ac86e-89c2-4d02-8d2d-614d2117bd2c</id>
<order>
<paymentPlanId>568</paymentPlanId>
</order>
</subscription>
Response
- JSON
Status Code: 200 OK
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Content-Encoding: gzip
Content-Length: 1178
Content-Type: application/json;charset=UTF-8
Date: Sat, 15 Aug 2015 20:03:31 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": "902ac86e-89c2-4d02-8d2d-614d2117bd2c",
"creationDate": "2015-08-15T12:46:43-06:00",
"externalAccountId": "825e63bf-1ba9-46a5-9237-3a715b467d38",
"status": "ACTIVE",
"order": {
"id": "1610",
"startDate": "2015-08-15T00:00:00-06:00",
"endDate": "2015-08-15T00:00:00-06:00",
"nextBillingDate": "2015-08-15T14:03:30-06:00",
"status": "ONE_TIME",
"frequency": "ONE_TIME",
"currency": "USD",
"type": "MIGRATION",
"totalPrice": "10.6300000000",
"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/api/marketplace/v1/products/78/editions/465/paymentPlans/568",
"id": "568",
"uuid": "e52ff207-2a17-4c58-85f3-6d49a23136af",
"frequency": "ONE_TIME",
"contract": {
"blockContractDowngrades": "false",
"blockContractUpgrades": "false",
"blockSwitchToShorterContract": "false"
},
"allowCustomUsage": "false",
"keepBillDateOnUsageChange": "false",
"separatePrepaid": "false",
"isPrimaryPrice": "false",
"costs": [
{
"unit": "NOT_APPLICABLE",
"minUnits": "0.0000000000",
"meteredUsage": "false",
"increment": "1.0000000000",
"pricePerIncrement": "false",
"blockContractDecrease": "false",
"blockContractIncrease": "false",
"blockOriginalContractDecrease": "false",
"amount": {
"CAD": "10",
"CHF": "10",
"EUR": "1",
"SEK": "10",
"USD": "10"
}
]
},
"previousOrder": {
"-id": "1608",
"-href": "https://www.appdirect.com/api/billing/v1/orders/1608"
},
"paymentPlanId": "568",
"activated": "false",
"oneTimeOrders": {
"oneTimeOrder": {
"id": "1609",
"startDate": "2015-08-15T00:00:00-06:00",
"endDate": "2015-09-01T00:00:00-06:00",
"nextBillingDate": "2015-09-01T00:00:00-06:00",
"status": "ONE_TIME",
"frequency": "MONTHLY",
"currency": "USD",
"type": "CREDIT",
"totalPrice": "-10.6300000000",
"paymentPlan": {
"-id": "541",
"-href": "http://localhost:8080/api/marketplace/v1/products/78/editions/440/paymentPlans/541"
}
}
},
"orderLines": {
"orderLine": [
{
"description": "LATEST AUTO_WEBAPP_NEW - One Time - Flat Rate Price - One Time Fee",
"id": "2494",
"price": "10.0000000000",
"quantity": "1.0000000000",
"totalPrice": "10.0000000000",
"type": "ITEM",
"unit": "NOT_APPLICABLE"
},
{
"description": "Sales Tax",
"id": "2495",
"percentage": "6.3000000000",
"quantity": "1.0000000000",
"totalPrice": "0.6300000000",
"type": "TAX"
}
]
}
},
"user": {
"-id": "3d4d2342-b7c4-4865-85bd-842f269adae6",
"-href": "http://localhost:8080/api/account/v1//users/3d4d2342-b7c4-4865-85bd-842f269adae6"
},
"company": {
"-id": "a012bb88-c2c5-40a1-b140-ec6ed4593b78",
"-href": "http://localhost:8080/api/account/v1//companies/a012bb88-c2c5-40a1-b140-ec6ed4593b78"
},
"product": {
"-id": "78",
"-href": "http://localhost:8080/api/marketplace/v1/products/78"
},
"edition": {
"-id": "465",
"-href": "http://localhost:8080/api/marketplace/v1/products/78/editions/465"
}
}
- XML
Status Code: 200 OK
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Content-Encoding: gzip
Content-Length: 1178
Content-Type: application/xml;charset=UTF-8
Date: Sat, 15 Aug 2015 20:03:31 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="https:://www.w3.org/2005/Atom">
<id>902ac86e-89c2-4d02-8d2d-614d2117bd2c</id>
<creationDate>2015-08-15T12:46:43-06:00</creationDate>
<externalAccountId>825e63bf-1ba9-46a5-9237-3a715b467d38</externalAccountId>
<status>ACTIVE</status>
<order>
<id>1610</id>
<startDate>2015-08-15T00:00:00-06:00</startDate>
<endDate>2015-08-15T00:00:00-06:00</endDate>
<nextBillingDate>2015-08-15T14:03:30-06:00</nextBillingDate>
<status>ONE_TIME</status>
<frequency>ONE_TIME</frequency>
<currency>USD</currency>
<type>MIGRATION</type>
<totalPrice>10.6300000000</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/465/paymentPlans/568">
<id>568</id>
<uuid>e52ff207-2a17-4c58-85f3-6d49a23136af</uuid>
<frequency>ONE_TIME</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>
<EUR>1</EUR>
<SEK>10</SEK>
<USD>10</USD>
</amount>
</cost>
</costs>
</paymentPlan>
<previousOrder id="1608" href="https:://www.appdirect.com/api/billing/v1/orders/1608"/>
<paymentPlanId>568</paymentPlanId>
<activated>false</activated>
<oneTimeOrders>
<oneTimeOrder>
<id>1609</id>
<startDate>2015-08-15T00:00:00-06:00</startDate>
<endDate>2015-09-01T00:00:00-06:00</endDate>
<nextBillingDate>2015-09-01T00:00:00-06:00</nextBillingDate>
<status>ONE_TIME</status>
<frequency>MONTHLY</frequency>
<currency>USD</currency>
<type>CREDIT</type>
<totalPrice>-10.6300000000</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 - One Time - Flat Rate Price - One Time Fee</description>
<id>2494</id>
<price>10.0000000000</price>
<quantity>1.0000000000</quantity>
<totalPrice>10.0000000000</totalPrice>
<type>ITEM</type>
<unit>NOT_APPLICABLE</unit>
</orderLine>
<orderLine>
<description>Sales Tax</description>
<id>2495</id>
<percentage>6.3000000000</percentage>
<quantity>1.0000000000</quantity>
<totalPrice>0.6300000000</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="465" href="https:://www.appdirect.com/api/marketplace/v1/products/78/editions/465"/>
</subscription>
Was this page helpful?
Tell us more…
Help us improve our content. Responses are anonymous.
Thanks
We appreciate your feedback!