Change Subscription's Resources

The Change Subscription's Resources method creates a new Order to change Subscription's Resources and returns the ID and body of the created Order.

POST /api/vendor/v1/subscriptions/{id}/change.json?api_token={api_token}&resources[][id]={resourece_id}&resources[][quantity]={quantity}&promo_code={promo_code}

Arguments

Name

Parameter Type

Data type

Required/ Optional

Description

idpathintegerRequiredAn ID of the existing subscription.
api_tokenquerystringRequiredAPI token of the manager who perform the operation (see API Token Authentication).
resources[][id]queryintegerRequiredAn ID of the subscription's resource.
resources[][quantity]queryintegerRequiredAn amount of the additional resources. A negative value is used for the resource downgrading.
promo_code

query

string

Optional

A promo code, which is used to get the discount.

Response model

Name

Data type

Description

id

integer

An order ID.

document_id

string

Order number.

status

string

One of the following statuses of the order:

  • waiting for payment - an order has been placed by a customer, the payment is expected;
  • provisioning - an order has been accepted, the service is provided;
  • provisioning failed - an order has been accepted, but the service is not provided;
  • completed - an order has been successfully processed;
  • cancelled - an order has been cancelled by a customer.

account_id

integer

An account ID, which was used to pay for the order.

type

string

One of the following types of order:

  • SalesOrder - a customer has ordered services;
  • RenewalOrder  - a customer has renewed a subscription;
  • ChangeOrder - a customer has purchased or refused additional resources;
  • SwitchOrder  - a customer has switched from one Plan to another.

created_at

date

A date and time of the order's creation.

updated_at

date

A date and time when the order was changed last time.

expiration_date

date

A date, by which the order must be paid (the order status must be confirmed). The date is calculated using the Grace period, which is set in the Plan Class page (see Creating a service term in the ActivePlatform. Operator Control Panel).

total

float

A total amount of the order.

promo_code

string

A promo code, which was used to get the discount (see Managing promo codes in the ActivePlatform. Operator Control Panel).

payment_id

integer

A payment ID, which is linked to the order.

items

arrayA list of items in the order:
  • id - an item ID of the order;
  • target_id - an entity ID (service or additional resource), which is related to the item of the order;

  • target_type - an entity type, which is related to the item of the order:

    • Subscription - a subscription;

    • SubscriptionResource - an additional resource of the subscription;

  • type - an internal item type of the order:

    • "ProvisioningItem::Upgrade" - increasing an amount of the subscription's resources;

    • "ProvisioningItem::New" - a new subscription;

    • "ProvisioningItem::RegisterDomain" - a domain registration;

    • "ProvisioningItem::Renew" - a renewal of the subscription;

    • "ProvisioningItem::SwitchPlan" - changing a plan within the subscription;

    • "ProvisioningItem::Downgrade" - decreasing an amount of the subscription's resources;

    • "ProvisioningItem::TransferDomain" - transferring a domain;

    • "ProvisioningItem::RegisterCertificate" - a registration of the SSL-certificate.

  • status - a current status of the order's item:

    • waiting for payment - an order has been placed by a customer, the payment is expected;
    • provisioning - an order has been accepted, the service is provided;
    • provisioning failed - an order has been accepted, but the service is not provided;
    • completed - an order has been successfully processed;
    • cancelled - an order has been cancelled by a customer.
  • description - a brief description of the order's item.

charges

array

A list of charges, which were created by the order:

  • id -  a charge ID;
  • subscription_id - a subscription ID;
  • subscription_resource_id - a subscription's resource ID;
  • subscription_resource_name - a name of the subscription's resource;
  • plan_resource_id - an ID of the plan resource;
  • resource_id - a resource ID;
  • quantity - a total quantity of the ordered resources;
  • operate_from - a begin date of the paid period;
  • operate_to - an end date of the paid period;
  • duration - a fraction of the paid period of the month;
  • description - detailed information about the charge;
  • unit_price - a price of the unit of the service;
  • amount - an amount of the charge;
  • status - a current status of the charge:
    • new - a charge was created;
    • opened - a charge was created, but the funds weren't blocked and weren't writing off from the account balance (for CSP subscriptions);
    • blocked - a charge was created, but wasn't paid, funds were blocked on the account balance;
    • waiting for a refund - a user performed the operation that must be approved by the manager in order to make a refund;
    • closed - funds were written off from the account balance;
    • deleted - a change was deleted;
    • refunded - funds have been successfully returned to the account balance. 
    • waiting for approve - a user performed the operation that must be approved by a manager.
  • type - an internal class of charge:
    • "Charge::Setup" - a charge for the subscription setup;
    • "Charge::Recurring" - a charge for the recurring fee of the subscription;
    • "Charge::Renewal" - a charge for the renewing of the subscription;
    • "Charge::RecurringResource" - a charge for the recurring fee of the subscription's resource;
    • "Charge::SetupResource" - a charge for the setup of the subscription's resource;
    • "Charge::Transfer" - a charge for the domain transferring.
  • order_id - an order ID, for which the charge is related;
  • close_date - a date when the charge will be closed;
  • created_at - a date and time of the charge creation;
  • updated_at - a date and time when the charge was updated last time.

Request example

POST http://billing.activeplatform.com:80/api/vendor/v1/subscriptions/2005786/change?api_token=654321&resources[][id]=132341&resources[][quantity]=3

 

Response example

{
  "id": 2010322,
  "document_id": "CO000157",
  "status": "waiting_for_payment",
  "account_id": 2000532,
  "type": "ChangeOrder",
  "created_at": "2016-09-01T12:44:54.222+03:00",
  "updated_at": "2016-09-01T12:44:54.538+03:00",
  "expiration_date": "2016-09-01",
  "total": 0.02,
  "promo_code": null,
  "payment_id": 2006917,
  "items": [
    {
      "id": 16577,
      "target_id": 132341,
      "target_type": "SubscriptionResource",
      "type": "ProvisioningItem::Upgrade",
      "status": "waiting_for_payment",
      "description": "Users"
    }
  ],
  "charges": [
    {
      "id": 754132,
      "subscription_id": 2005786,
      "subscription_resource_id": 132341,
      "subscription_resource_name": "Users",
      "plan_resource_id": 2000854,
      "resource_id": 2002273,
      "quantity": 3,
      "operate_from": "2016-09-15",
      "operate_to": "2016-09-26",
      "duration": 0.367,
      "description": "Upgrade resource (recurring fee) \"Users"\ for Subscription #2005786 \"Microsoft Exchange 2013\"",
      "unit_price": 0.01,
      "amount": 0.01,
      "status": "new",
      "type": "Charge::Recurring",
      "order_id": 2010322,
      "close_date": "2016-09-26",
      "created_at": "2016-09-01T12:44:54.434384+0300",
      "updated_at": "2016-09-01T12:44:54.434384+0300"
    }
  ]
}