Get list of end-customer charges

The Get list of end-customer charges method returns the list of end-customers charges of the current reseller or any of its downstream resellers.

An API token of a manager is required for authorization. To get an API token via the Operator Control Panel, see Viewing and updating manager's information.

The manager's API token specified in an API request determines:

The role and access level of the manager, which determine the availability of a method.
The current reseller and downstream resellers accessible within a method.

GET {base_url}/api/v3/resellers/{reseller_id}/charges

Arguments

Name

Parameter Type

Data type

Required/
Optional

Description

X-Api-Token header string Required API token of a manager that performs the operation (see Viewing and updating manager's information)

Content-Type header string Required Media type of the request. Specify the following: application/vnd.api+json

Accept

header

string

Required

Supported media types of the answer. Specify the following: application/vnd.api+json

base_url path string Required ActivePlatform URL

reseller_id path integer Required ID of the current reseller or any of its downstream resellers (see Viewing and updating reseller general information)

page[size] query integer Optional Page navigation: number of elements per page. The default value is 50

page[number] query integer Optional Page navigation: page number

filter[close_date]

query

string

Optional

Filtering charges by the close date in the YYYY-MM-DD format. To specify the period, the following filters are used:

filter[close_date][gt] — close date is greater than the specified date.
filter[close_date][lt] — close date is less than the specified date.

filter[subscription_id]

query

integer

Optional

Filtering charges by the subscription ID

filter[status]

query

string

Optional

Filtering charges by the status (for the list of charge statuses, see Charges attributes)

filter[created_at]

query

string

Optional

Filtering charges by the date and time of the charge creation in the YYYY-MM-DDTHH:MM:SS format for the platform time zone or in the specified time zone (for example, YYYY-MM-DDTHH:MM:SSZ for UTC, see RFC 3339). To specify the period, the following filters are used:

filter[created_at][gt] — date and time are greater than the specified.
filter[created_at][lt] — date and time are less than the specified.

filter[updated_at]

query

string

Optional

Filtering charges by the date and time when the charge was updated in the YYYY-MM-DDTHH:MM:SS format for the platform time zone or in the specified time zone (for example, YYYY-MM-DDTHH:MM:SSZ for UTC, see RFC 3339). To specify the period, the following filters are used:

filter[updated_at][gt] — date and time are greater than the specified.
filter[updated_at][lt] — date and time are less than the specified.

filter[plan_class_ids]

query

string

Optional

Filtering charges by the service term ID (see Viewing the list of service terms). Several IDs must be separated by a comma

filter[billing_date]

query

string

Optional

Filtering closed charges by the start date of the related billing period in the YYYY-MM-DD format

include

query

string

Optional

Returns additional information about objects related to charges. The parameter can be a comma-separated list if information about several objects is required. The following objects and possible values are supported:

Object	Parameter value
Reseller	`reseller`
Account	`account`
Subscription	`subscription`
Plan	`plan`
Taxes	`taxes`
Order (except for PAYG subscriptions)	`order`

Response model

Name

Data type

Description

data array Response data

id

string

ID of the charge

type string Data type

attributes object Information about the charge

created_at string Date and time of the charge creation

updated_at string Date and time when the charge was updated

subscription_id integer ID of the customer's subscription

subscription_resource_id integer ID of the resource in the customer's subscription

operate_from

string

The start date of the period paid by the charge (YYYY-MM-DD)

description string Charge details description

unit_price string The unit price of the service or resource in the plan currency

amount string The amount of the charge (taxes included) in the reseller currency

status string Status of the charge (for the list of charge statuses, see Charges attributes)

type

string

Type of the charge (see also Charges attributes)

Charge::Setup — a non-recurring charge for service setup.
Charge::Recurring — a monthly charge for service usage.
Charge::RecurringResource — a monthly charge for resource usage.
Charge::Renewal — a non-recurring charge for service renewal.
Charge::RenewalResource — a non-recurring charge for resource renewal.
Charge::ExternalResource — an accumulative charge based on the consumed resources records.
Charge::SetupResource — a non-recurring charge for resource setup.
Charge::Transfer — a non-recurring charge for subscription transfer.

net_cost

string

For plans created on the reseller level — the net cost of the charge in the reseller currency calculated as follows:
```
net_cost = cost × duration × quantity × net_cost_currency_rate / net_cost_currency_unit
```
where cost is the net cost of a resource or period in the plan for the corresponding charge type.
For delegated plans — the net cost of the charge in the upstream reseller currency equal to the amount of the linked reseller charge.

If the charge is not closed, net_cost = null

tax_is_calculated_using

string

The Tax is calculated using option in the system settings at the moment of the charge creation (see Taxes calculation settings):

net_prices — Plan prices without tax included — prices in the plan do not include taxes.
gross_prices — Plan prices with tax included — prices in the plan include taxes.

net_amount string The amount of the charge (taxes excluded) in the reseller currency

taxes_amount string The amount of taxes for the charge in the reseller currency

net_cost_original

string

The net cost of the charge in the plan currency:

For plans created on the reseller level — calculated as follows:
```
net_cost_original = cost × duration × quantity
```
where cost is the net cost of a resource or period in the plan for the corresponding charge type.
For delegated plans — calculated as follows:
```
net_cost_original = amount × net_cost_currency_unit / net_cost_currency_rate
```
where amount is the amount of the linked reseller charge in the upstream reseller currency.

If the charge is not closed, net_cost_original = null

net_cost_currency_rate

string

For plans created on the reseller level — the exchange rate from the reseller currency to the plan currency set on the reseller level and used to calculate the charge net cost.
For delegated plans — the exchange rate from the upstream reseller currency to the plan currency set on the upstream reseller level and used to calculate the charge net cost.

net_cost_currency_unit

integer

For plans created on the reseller level — the currency units used for the exchange rate set on the reseller level to calculate the charge net cost.
For delegated plans — the currency units used for the exchange rate set on the upstream reseller level to calculate the charge net cost.

unit_price_currency string The plan currency code for the unit price

quantity number The number of ordered services or resources

duration number Period of the charge (in months). For example, 1 day = 0.033, 2 years = 24

subscription_resource_name string Name of the resource in the customer's subscription

plan_resource_id integer Name of the resource in the customer's plan

resource_id integer ID of the resource

order_id integer ID of the order

operate_to string The finish date of the period paid by the charge (YYYY-MM-DD)

close_date

string

The close date of the charge (YYYY-MM-DD)

billing_date string Start date of the billing period related to a closed charge (YYYY-MM-DD)

application_template_key string Key of the application template linked to the subscription (see Viewing and updating connector details)

additional_params

array of objects

Additional parameters of the charge for services based on the following plugins:

MicrosoftCspProducts:

Name	Data type	Description
tenant_id	string	The Tenant ID in Microsoft Partner Center
tenant_name	string	The Tenant name (domain) in Microsoft Partner Center
ms_subscription_id	string	The subscription ID on the Microsoft side (external ID)
order_id	string	The order ID on the Microsoft side
alternate_id	string	The alternate order ID on the Microsoft side
product_id	string	The Microsoft Product ID of a resource linked to the charge (for an example, see Fetching the list of resources for the Microsoft Software Subscriptions service)
sku_id	string	The SKU of a resource on the Microsoft side linked to the charge (for an example, see Fetching the list of resources for the Microsoft Software Subscriptions service)
term_duration	string	The Term Duration of a subscription on the Microsoft side. For example, P1M or P1Y
billing_cycle	string	The Billing Cycle of a subscription on the Microsoft side. For example, Monthly or Annual
attribute_type	string	Information about the purpose of the charge for subscriptions to the Microsoft Azure Plan service (see Resource consumption records for the Microsoft Azure Plan service): azure_plan — basic consumption within the Microsoft Azure Plan subscription. azure_ri — reserved resources (Azure RI). 3rd_party — third-party resources. azure_savings — the Azure Savings Plan service.
effective_cost	number	The net cost of the charge for the reseller with the applied PEC discount from Microsoft. Only for subscriptions to the Microsoft Azure Plan service (see Resource consumption records for the Microsoft Azure Plan service)
azure_plan_id	string	The ID of an Azure Plan "container" with the customer's subscriptions. Only for subscriptions to the Microsoft Azure Plan service (see Ordering a Microsoft Azure Plan subscription via the Operator Control Panel)

Manual Provisioning Plugin:

Name	Data type	Description
tenant_name	string	The primary name of the account ordered the subscription (see Get account)
tenant_id	string	The ID of the account ordered the subscription
order_id	string	The ID of the sales order linked to the subscription
subscription_id	string	The subscription ID
offer_id	string	The SKU of a plan linked to the subscription (see Get plan)

Office365:

Name	Data type	Description
tenant_name	string	The Tenant name (domain) in Microsoft Partner Center
tenant_id	string	The Tenant ID in Microsoft Partner Center
order_id	string	The order ID on the Microsoft side
subscription_id	string	The subscription ID on the Microsoft side
offer_id	string	The Plan SKU or Addon SKU in Microsoft Partner Center

Vendor Service Plugin (VSP):

Name	Data type	Description
external_id	string	The External ID of an application
plan_sku	string	The plan SKU
subscription_attributes	object	Subscription attributes created in Vendor Portal (the password attribute excluded)
resource_key	string	The key of an application resource
attribute_type	string	Information about the purpose of the charge: google_cloud — the final charge of a subscription to the Google Cloud Platform service (see Resource consumption records for the Google Cloud Platform service). The parameter is absent in other cases.
effective_cost	number	The net cost of the final charge for the reseller. Only for subscriptions to the Google Cloud Platform service (see Resource consumption records for the Google Cloud Platform service). The parameter is absent in other cases.

In other cases, returns an empty array

discount string The amount of the discount for the charge in the reseller currency

original_amount

string

The amount of the charge in the plan currency

original_amount_currency string The plan currency code for the charge amount

currency_rate string The exchange rate from the reseller currency to the plan currency set on the reseller level and used to calculate the charge amount

currency_unit integer The currency units used for the exchange rate set on the reseller level to calculate the charge amount

net_cost_original_currency string The plan currency code for the charge net cost

relationships

object

Related objects

Reseller charges are simultaneously related to the parent plan and the subscription plan resource.
When switching a subscription plan, old charges of the subscription and new charges for a refund remain related to the old plan and its resources. All other new charges will be related to the new plan and its resources.

taxes object Taxes information

data

array of objects

Related object information:

Name		Data type	Description
id		string	ID of the object
type		string	Data type

reseller object Reseller information

data

object

Related object information:

Name		Data type	Description
id		string	ID of the object
type		string	Data type

account object Account information

data

object

Related object information:

Name		Data type	Description
id		string	ID of the object
type		string	Data type

subscription object Subscription information

data

object

Related object information:

Name		Data type	Description
id		string	ID of the object
type		string	Data type

plan object Plan information

data

object

Related object information:

Name		Data type	Description
id		string	ID of the object
type		string	Data type

plan_resource object Plan resource information

data

object

Related object information:

Name		Data type	Description
id		string	ID of the object
type		string	Data type

discount object Discount information

data

object

Related object information:

Name		Data type	Description
id		string	ID of the object
type		string	Data type

order

object

Order information

data

object

Related object information:

Name		Data type	Description
id		string	ID of the object
type		string	Data type

included

array

Additional information about objects listed in the request:

Name	Data type	Description
id	string	ID of the object
type	string	Data type
attributes	object	Attributes of the object (see details below)

For a reseller, see the data model in Get downstream reseller.
For a account, see the data model in Get account.
For a plan, see the data model in Get plan.
For an order, see the data model in Get order.
For a subscription:

Name			Data type	Description
id			string	ID of the subscription
type			string	Data type
attributes			object	Subscription details
	created_at		string	Date and time of the subscription creation
	updated_at		string	Date and time when the subscription was updated
	auto_renewal		bool	The automatic subscription renewal option: true — the automatic subscription renewal is enabled. false — the automatic subscription renewal is off.
	billing_from		string	The start date of generating charges for the subscription (YYYY-MM-DD)
	expiration_date		string	The expiration date of the subscription (YYYY-MM-DD)
	name		string	Name of the subscription
	auto_renew_point_days		integer	Auto-renew point (in days)
	start_date		string	The date of activation of the subscription (YYYY-MM-DD)
	status		string	Status of the subscription (for the list of subscription statuses, see Viewing the list of resellers subscriptions)
	payment_model		string	Subscription payment model: prepay postpay
	payment_model_parameters		object	Payment model parameters
		credit_limit	number	The value of the subscription debt, above which the postpaid subscription will be stopped. For postpaid subscriptions only (`payment_model = postpay`)
		current_debt	number	The subscription debt that is calculated as the total amount of all blocked charges for the subscription for the current billing period. For postpaid subscriptions only (`payment_model = postpay`)

For every tax used to calculate the charge:

Название		Тип данных	Описание
id		string	The tax ID
type		string	Data type
attributes		object	Tax details
	created_at	string	Date and time of the tax creation
	updated_at	string	Date and time when the tax was updated
	charge_id	integer	The ID of the related charge
	origin_id	integer	The tax ID in the taxation module
	name	string	The tax name
	code	string	The tax code
	rate	number	The tax rate percentage
	amount	string	The tax amount in the reseller currency calculated for `net_amount` of the charge

links array Page navigation links that use the defined page navigation parameters

self string Current page link

first string First page link

prev string Previous page link

next string Next page link

last string Last page link

meta object Additional information about the charge

currency string Reseller currency code

Request example

GET /api/v3/resellers/1/charges?page[size]=2&page[number]=1995
Host: test.activeplatform.com
Content-Type: application/vnd.api+json
X-Api-Token: vY5fwetestK3gJXZH5uHCw
Accept: application/vnd.api+json

Response example

{
    "data": [
        {
            "id": "7302",
            "type": "charges",
            "attributes": {
                "created_at": "2023-02-25T04:12:17.520233+0000",
                "updated_at": "2023-02-25T04:12:18.343218+0000",
                "subscription_id": 1728,
                "subscription_resource_id": 2076,
                "operate_from": "2023-11-01",
                "description": "Upgrade resource (recurring fee) \"Licenses\" for Subscription #1728 \"Office\"",
                "unit_price": "30.0",
                "amount": "18.15",
                "status": "refunded",
                "type": "Charge::Recurring",
                "net_cost": null,
                "net_amount": "15.0",
                "taxes_amount": "3.15",
                "net_cost_original": null,
                "net_cost_currency_rate": "1.0",
                "net_cost_currency_unit": 1,
                "unit_price_currency": "USD",
                "quantity": 1.0,
                "duration": 1.0,
                "subscription_resource_name": "Licenses",
                "plan_resource_id": 1335,
                "resource_id": 4943,
                "order_id": 3595,
                "operate_to": "2023-11-30",
                "close_date": "2023-11-30",
                "billing_date": null,
                "application_template_key": "",
                "additional_params": [
                    {
                        "tenant_name": "XXXXX",
                        "tenant_id": 246,
                        "order_id": 3595,
                        "subscription_id": 1728,
                        "offer_id": ""
                    }
                ],
                "discount": "15.00",
                "original_amount": "18.15",
                "original_amount_currency": "USD",
                "currency_rate": "1.0",
                "currency_unit": 1,
                "net_cost_original_currency": "USD",
                "tax_is_calculated_using": "net_prices"
            },
            "relationships": {
                "taxes": {
                    "data": [
                        {
                            "id": "8889",
                            "type": "taxes"
                        },
                        {
                            "id": "8890",
                            "type": "taxes"
                        },
                        {
                            "id": "8891",
                            "type": "taxes"
                        }
                    ]
                },
                "reseller": {
                    "data": {
                        "id": "1",
                        "type": "resellers"
                    }
                },
                "account": {
                    "data": {
                        "id": "246",
                        "type": "accounts"
                    }
                },
                "subscription": {
                    "data": {
                        "id": "1728",
                        "type": "subscriptions"
                    }
                },
                "plan": {
                    "data": {
                        "id": "1253",
                        "type": "plans"
                    }
                },
                "plan_resource": {
                    "data": {
                        "id": "1335",
                        "type": "plan_resources"
                    }
                },
                "discount": {
                    "data": {
                        "id": "9",
                        "type": "discounts"
                    }
                },
                "order": {
                    "data": {
                        "id": "2",
                        "type": "sales_orders"
                    }
                }
            }
        },
        {
            "id": "7303",
            "type": "charges",
            "attributes": {
                "created_at": "2023-02-25T04:12:17.533114+0000",
                "updated_at": "2023-02-25T04:12:18.350008+0000",
                "subscription_id": 1728,
                "subscription_resource_id": 2076,
                "operate_from": "2023-12-01",
                "description": "Upgrade resource (recurring fee) \"Licenses\" for Subscription #1728 \"Office\"",
                "unit_price": "30.0",
                "amount": "18.15",
                "status": "refunded",
                "type": "Charge::Recurring",
                "net_cost": null,
                "net_amount": "15.0",
                "taxes_amount": "3.15",
                "net_cost_original": null,
                "net_cost_currency_rate": "1.0",
                "net_cost_currency_unit": 1,
                "unit_price_currency": "USD",
                "quantity": 1.0,
                "duration": 1.0,
                "subscription_resource_name": "Licenses",
                "plan_resource_id": 1335,
                "resource_id": 4943,
                "order_id": 3595,
                "operate_to": "2023-12-31",
                "close_date": "2023-12-31",
                "billing_date": null,
                "application_template_key": "",
                "additional_params": [
                    {
                        "tenant_name": "XXXXX",
                        "tenant_id": 246,
                        "order_id": 3595,
                        "subscription_id": 1728,
                        "offer_id": ""
                    }
                ],
                "discount": "15.00",
                "original_amount": "18.15",
                "original_amount_currency": "USD",
                "currency_rate": "1.0",
                "currency_unit": 1,
                "net_cost_original_currency": "USD",
                "tax_is_calculated_using": "net_prices"
            },
            "relationships": {
                "taxes": {
                    "data": [
                        {
                            "id": "8892",
                            "type": "taxes"
                        },
                        {
                            "id": "8893",
                            "type": "taxes"
                        },
                        {
                            "id": "8894",
                            "type": "taxes"
                        }
                    ]
                },
                "reseller": {
                    "data": {
                        "id": "1",
                        "type": "resellers"
                    }
                },
                "account": {
                    "data": {
                        "id": "246",
                        "type": "accounts"
                    }
                },
                "subscription": {
                    "data": {
                        "id": "1728",
                        "type": "subscriptions"
                    }
                },
                "plan": {
                    "data": {
                        "id": "1253",
                        "type": "plans"
                    }
                },
                "plan_resource": {
                    "data": {
                        "id": "1335",
                        "type": "plan_resources"
                    }
                },
                "discount": {
                    "data": {
                        "id": "9",
                        "type": "discounts"
                    }
                },
                "order": {
                    "data": {
                        "id": "2",
                        "type": "sales_orders"
                    }
                }
            }
        }
    ],
    "links": {
        "self": "https://test.activeplatform.com/api/v3/resellers/1/charges?page%5Bnumber%5D=1995&page%5Bsize%5D=2",
        "first": "https://test.activeplatform.com/api/v3/resellers/1/charges?page%5Bnumber%5D=1&page%5Bsize%5D=2",
        "prev": "https://test.activeplatform.com/api/v3/resellers/1/charges?page%5Bnumber%5D=1994&page%5Bsize%5D=2",
        "next": "https://test.activeplatform.com/api/v3/resellers/1/charges?page%5Bnumber%5D=1996&page%5Bsize%5D=2",
        "last": "https://test.activeplatform.com/api/v3/resellers/1/charges?page%5Bnumber%5D=1996&page%5Bsize%5D=2"
    },
    "meta": {
        "currency": "USD"
    }
}