Accounting

Contracts

AccountingLocationRepositoryContract

The repository to get, create, update and delete accounting locations.

Namespace

Plenty\Modules\Accounting\Contracts

Methods

public get(int $id):AccountingLocation

Get an accounting location. The ID of the location must be specified.

Parameters
int $id
public listByPlentyId(int $plentyId):void

List accounting locations for a client. The plenty ID of the client must be specified.

Parameters
int $plentyId
public create(array $data):AccountingLocation

Create an accounting location.

Parameters
array $data
public update(int $id, array $data):AccountingLocation

Update an accounting location. The ID of the location must be specified.

Parameters
int $id
array $data
public delete(int $id):bool

Delete an accounting location. The ID of the location must be specified.

Parameters
int $id

AccountingServiceContract

Provides methods to detect a location ID.

Namespace

Plenty\Modules\Accounting\Contracts

Methods

public detectLocationId(int $plentyId, int $countryId = null):int

Get a location ID for a country of delivery. The plenty ID must be specified and the ID of the country of delivery can be specified. If the ID of a country is not specified, the ID of the standard location of the specified client will be returned.

Parameters
int $plentyId The plenty ID of the client (store). The default client will be used if the plenty ID is not specified.
int $countryId The ID of the country of delivery. The standard location of the specified client will be returned, if no ID of a country of delivery is specified.
public detectLocationIdByClientId(int $clientId = null, int $countryId = null):int

Get the location ID for a country of delivery. The ID of the client and the ID of the country of delivery can be specified. If neither the client ID nor the ID of a country are specified, the ID of the standard location of the default client will be returned.

Parameters
int $clientId The ID of the client. The default client (ID 0) will be used if the ID of client is not specified.
int $countryId The ID of the country of delivery. The standard location of the specified client will be returned, if no ID of a country of delivery is specified.
public getAccountingLocations(int $plentyId, int $countryId = null):array

List accounting locations. The plenty ID must be specified and the ID of a country of delivery can be specified. If the ID of the country is specified, only one accounting location will be returned. If the ID of the country is not specified, all accounting locations of the client will be returned.

Parameters
int $plentyId The plenty ID of the client (store).
int $countryId The ID of the country of delivery.
public getAccountingLocationsByClient(int $clientId = null, int $countryId = null):array

List accounting locations. The ID of the client and the ID of the country of delivery can be specified. If neither the client ID nor the ID of a country are specified, all accounting locations of the default client will be returned.

Parameters
int $clientId The ID of the client. The default client (ID 0) will be used if the ID of client is not specified.
int $countryId The ID of the country of delivery.

DebtorAccountRepositoryContract

The DebtorAccountRepositoryContract is the interface for the DebtorAccountRepository. This interface allows you to either list debtor accounts by locationId or by locationId and mode. The mode describes the criteria that is used to assign pending amounts to debtor accounts.

Namespace

Plenty\Modules\Accounting\Contracts

Methods

public findByLocationId(int $locationId):DebtorAccountConfiguration

Get debtor account configuration of an accounting location. The ID of the accounting location must be specified.

Parameters
int $locationId The ID of the accounting location.
public listByLocationIdAndMode(int $locationId, string $mode):void

Lists debtor accounts by mode for an accounting location . The mode and the accounting location must be specified.

Parameters
int $locationId The ID of the accounting location.
string $mode Specifies the mode of the debtor accounts. There are 4 different modes available. These modes are:
  • character
  • country
  • payment
  • country_payment
The modes are described in detail in the DebtorAccountConfiguration model as well as DebtorAccount model.

DetermineShopCountryContract

This interface provides methods to initialise the country of a location or the country of an order as well as methods to get the ID of a client, the plenty ID of a client, the country or the ID of country.

Namespace

Plenty\Modules\Accounting\Contracts

Methods

public initByClientId(int $clientId):void

Initialise the country of the standard location of a client. The ID of the client must be specified.

Parameters
int $clientId The ID of the client [optional, default=0]
public initByPlentyId(int $plentyId):void

Initialise the country of the standard location of a client. The plenty ID of the client can be specified. If no plenty ID is specified, the standard client will be used.

Parameters
int $plentyId The plenty ID of the client [optional]
public initByLocationId(int $locationId):void

Initialise the country of a location. The ID of the location must be specified.

Parameters
int $locationId The ID of the location
public initByOrderId(int $orderId):void

Initialise the country for an order. The ID of the order must be specified.

Parameters
int $orderId The ID of the order
public getCountryId():int

Get the ID of the country of the current standard location. One of the initialise methods must be called first. The client that was initialised with the initialise method is your current client.

public getClientId():int

Get the ID of the current client. One of the initialise methods must be called first. The client that was initialised with the initialise method is your current client.

public getPlentyId():int

Get the plenty ID of the current client. One of the initialise methods must be called first. The client that was initialised with the initialise method is your current client.

public getCountryIdByClientId(int $clientId):int

Get the ID of the country of a client's standard location. The ID of the client must be specified.

Parameters
int $clientId The ID of the client. The ID of the default client will be used if no ID is specified [optional, default=0].
public getCountryIdByPlentyId(int $plentyId):int

Get the ID of the country of a client's standard location. The plenty ID of the client must be specified.

Parameters
int $plentyId The plenty ID of a client
public getCountryIdByClientIdAndCountryId(int $clientId, int $countryId):int

Get the country of a client's standard location. The ID of the client and the ID of the country must be specified.

Parameters
int $clientId The ID of the client.
int $countryId The ID of the country.
public getCountryIdByLocationId(int $locationId):int

Get the country of a location. The ID of the location must be specified.

Parameters
int $locationId The ID of the location.

PostingKeyRepositoryContract

The PostingKeyRepositoryContract is the interface for the PostingKeyRepository. This interface provides the functionality to find the posting keys for an accounting location.

Namespace

Plenty\Modules\Accounting\Contracts

Methods

public findByLocationId(int $locationId):PostingKeyConfiguration

Get the posting key configuration of an accounting location. The ID of the accounting location must be specified.

Parameters
int $locationId The ID of the accounting location

RevenueAccountRepositoryContract

The RevenueAccountRepositoryContract is the interface for the RevenueAccountRepository. This interface allows you to either list revenue accounts by locationId, find by locationId and countryId or to least all for an accounting location.

Namespace

Plenty\Modules\Accounting\Contracts

Methods

public listRevenueAccounts(int $page = 1, int $itemsPerPage = 50):PaginatedResult

List revenue account configurations for all accounting locations. Each accounting location has one revenue account configuration.

Parameters
int $page The page to get. The default page that will be returned is page 1.
int $itemsPerPage The number of revenue accounts to be displayed per page. The default number of revenue accounts is 50.
public findByLocationId(int $locationId):RevenueAccountLocationConfiguration

Get the revenue account configuration of an accounting location. The ID of the accounting location must be specified.

Parameters
int $locationId The ID of the accounting location
public findByLocationIdAndCountryId(int $locationId, int $countryId):RevenueAccountCountryConfiguration

Get the revenue account configuration of a country. The country account configuration is associated with an accounting location. The ID of the accounting location that the country is associated with as well as the ID of the country must be specified.

Parameters
int $locationId The ID of the accounting location
int $countryId The ID of the country

Exceptions

AccountingException

Class AccountingException

Namespace

Plenty\Modules\Accounting\Exceptions

Models

AccountingLocation

The accounting location model. An accounting location always has a country and belongs to a client. An accounting location contains the VAT configurations. The VAT model contains the VAT configuration.

Namespace

Plenty\Modules\Accounting\Models

Properties

Type Name Description
int id The ID of the accounting location
int countryId The ID of the country of the accounting location
string name The name of the accounting location
int clientId The ID of the client that the accounting location belongs to
int plentyId The plenty ID of the client that the accounting location belongs to
array vats A collection of VAT configurations that are related to the accounting location
Country country The country that the accounting location belongs to
Webstore client The client (store) this accounting location belongs to

Methods

public toArray()

Returns this model as an array.

DebtorAccount

The DebtorAccountValue Model which contains the actual configured debtor accounts by character, payment and country.

Namespace

Plenty\Modules\Accounting\Models

Properties

Type Name Description
int accountId The ID of the debtor account configuration that the debtor account belongs to
string mode The mode describes the criteria based on which pending amounts are assigned to a debtor account. The following modes are available:
  • character = The debtor accounts are selected based on the first character of customer information. The information and the order of the information that will be used are defined with the sequence. There are 3 different sequences available.
  • payment = The debtor accounts are selected based on the payment method.
  • country = The debtor accounts are selected based on the country of delivery.
  • country_payment = The debtor accounts are selected based on two criteria. The first criteria is the country and if the country is same as the country of the accounting location then the payment method is used to select the deptor account.
string key The key depends on the debtor account mode.
  • For the character mode the keys are letters. The letters indicate the first letter of the customer information that was used to assign the pending amounts.
  • For the payment mode the key is the ID of payment method.
  • For the country mode the key is the ID of the country.
  • For the country_payment mode the key is either the ID of the country or the ID of payment method. If the country is the same as the country of the accounting location then the payment methods are used to select the deptor account.
string value The actual debtor account.
DebtorAccountConfiguration account The debtor account configuration this account is associated with.

Methods

public toArray()

Returns this model as an array.

DebtorAccountConfiguration

The debtor account configuration model. The configuration is a set of debtor accounts. The actual number of debtor accounts within the configuration depends on the mode used to assign pending amounts to debtor accounts.

Namespace

Plenty\Modules\Accounting\Models

Properties

Type Name Description
int id The ID of the debtor account configuration
int locationId The ID of the accounting location that the debtor account is associated with.
string mode The mode describes the criteria based on which pending amounts are assigned to a debtor account. The following modes are available:
  • character = The debtor accounts are selected based on the first character of customer information. The information and the order of the information that will be used are defined with the sequence. There are 3 different sequences available.
  • payment = The debtor accounts are selected based on the payment method.
  • country = The debtor accounts are selected based on the country of delivery.
  • country_payment = The debtor accounts are selected based on two criteria. The first criteria is the country and if the country is same as the country of the accounting location then the payment method is used to select the deptor account.
string sequence The sequence defines the order in which customer information will be used for the debtor account assignment if the character made has been chosen. The following sequences are available:
  • FNV = stands for the sequence: company, lastname, firstname
  • NVF = stands for the sequence: lastname, firstname, company
  • NFV = stands for the sequence: lastname, company, firstname
string standard The standard debtor account that will be used if no matching debtor account can be found.
bool save Flag that indicates if the debtor account shall be saved within the contact data.
accounts The actual debtor accounts

Methods

public toArray()

Returns this model as an array.

PostingKey

The Posting Key Model. A posting key is always associated with an accounting location and holds an posting key for each configured vat rate.

Namespace

Plenty\Modules\Accounting\Models

Properties

Type Name Description
int id The Id posting key in relation to the vatrate.
string value The actual posting key for the vat rate.

Methods

public toArray()

Returns this model as an array.

PostingKeyConfiguration

The posting key configuration model. A posting key configuration is a set of 4 posting keys. A posting key configuration is always associated with an accounting location and can have a posting key per VAT rate. A posting key defines how line items are booked to accounts.

Namespace

Plenty\Modules\Accounting\Models

Properties

Type Name Description
int locationId The ID of the accounting location that the configuration belongs to
postingKeys The posting keys for this configuration
AccountingLocation location The name of the accounting location that the configuration belongs to

Methods

public toArray()

Returns this model as an array.

RevenueAccount

The revenue account model provides information on a single revenue account. The ID of an account matches the ID of a VAT rate.

Namespace

Plenty\Modules\Accounting\Models

Properties

Type Name Description
int id The ID of the account. The account IDs are always 0,1,2 or 3. This way the IDs indicate the VAT rate that the account is used for. The revenues that were made with items that have the VAT rate with the ID 0 are assigned to the account with the ID 0.
int account The actual account number that was entered in the entry field.

Methods

public toArray()

Returns this model as an array.

RevenueAccountCountryConfiguration

The revenue account country configuration model. The revenue account country configuration is a set of up to 4 revenue accounts for one country. Each country that you need to pay VAT in needs a configuration. The 4 revenue account included in the configuration are associated with VAT rates. The VAT rate that one revenue account is associated with can be identified by the ID of the VAT rate. The ID of the VAT rate is included in the account name. Furthermore, each revenue account country configuration is part of a revenue account location configuration. A revenue account country configuration is only available if a VAT configuration for the country exists.

Namespace

Plenty\Modules\Accounting\Models

Properties

Type Name Description
int countryId The ID of the country that the account configuration belongs to
int revenueAccountLocationId The ID configuration of the revenue account that these accounts are for.
revenueAccounts A list of the actual revenue accounts. The accounts are associated with VAT rate. The association can be identified by
Country country The country these accounts are associated with.
RevenueAccountLocationConfiguration locationConfiguration The revenue account configuration these accounts are associated with

Methods

public toArray()

Returns this model as an array.

RevenueAccountLocationConfiguration

The revenue account location configuration model. A revenue account location configuration is the set of all revenue accounts that belong to one accounting location.

Namespace

Plenty\Modules\Accounting\Models

Properties

Type Name Description
int id The ID of the revenue account configuration
int locationId The ID of the accounting location that the configuration belongs to
string accountEu The account used for revenues that are exempt from VAT and that were sold within the European Union
string accountExport The account used for revenues that are exempt from VAT and that were sold to outside the European Union
revenueAccountCountryConfigurations The set of revenue accounts of one country

Methods

public toArray()

Returns this model as an array.

Vat

Contracts

VatInitContract

This interface provides methods to initialise the detection of a VAT configuration and to actually detect VAT rates or VAT fields.

Namespace

Plenty\Modules\Accounting\Vat\Contracts

Methods

public init(int $billingCountryId, string $taxIdNumber, int $locationId, int $shippingCountryId, string $startedAt = null):void

Initialise the VAT system data

Parameters
int $billingCountryId The ID of the country of the invoice address
string $taxIdNumber The tax identification number
int $locationId The ID of the location
int $shippingCountryId The ID of the country of the shipping address. [optional, default=0]
string $startedAt The date when the VAT configuration went into effect. If no date is set, the current date will be used. [optional, default=null]
public isInitialized():bool

Get whether the VAT system is already initialised or not

public getVatField(float $vatRate, bool $restrictedToDigitalItems = false):int

Get the VAT field for a VAT rate

Parameters
float $vatRate The VAT rate to be used to find the VAT field
bool $restrictedToDigitalItems Flag that indicates if the VAT is restricted to digital items or not.
True = the VAT is restricted to digital items
False = the VAT is used for all items
public getVatRate(int $vatField, bool $restrictedToDigitalItems = false):float

Get the VAT rate of a VAT field

Parameters
int $vatField The VAT field (0-3).
bool $restrictedToDigitalItems Flag that indicates if the VAT is restricted to digital items or not.
True = the VAT is restricted to digital items
False = the VAT is used for all items
public getUsingVat(bool $restrictedToDigitalItems = false):Vat

Get the VAT configuration to be used for VAT calculation

Parameters
bool $restrictedToDigitalItems Flag that indicates if the VAT is restricted to digital items or not.
True = the VAT is restricted to digital items
False = the VAT is used for all items
public getUsingVatRates(bool $restrictedToDigitalItems = false):array

Get the VAT rates to be used for VAT calculation

Parameters
bool $restrictedToDigitalItems Flag that indicates if the VAT is restricted to digital items or not.
True = the VAT is restricted to digital items
False = the VAT is used for all items
public getStandardVatByLocationId(int $locationId, string $startedAt = null):Vat

Get a standard VAT configuration of an accounting location

Parameters
int $locationId The ID of the accounting location
string $startedAt The date when the VAT configuration went into effect. The date is in W3C format.

VatRepositoryContract

The VatRepositoryContract is the interface for the VAT functionality. This interface allows you to get the VAT configuration for an accounting location and a country of delivery.

Namespace

Plenty\Modules\Accounting\Vat\Contracts

Methods

public findById(int $id):Vat

Get a VAT configuration

Parameters
int $id The ID of the VAT configuration
public getStandardVat(int $plentyId = null, string $startedAt = null):Vat

Get the standard VAT configuration for a plenty ID

Parameters
int $plentyId The ID of the client (store)
string $startedAt The date when the VAT configuration went into effect. The date is given in W3C format.
public getStandardVatByLocation(int $locationId, string $startedAt = null):Vat

Get the standard VAT configuration for a location ID

Parameters
int $locationId The ID of the location.
string $startedAt The date when the VAT configuration went into effect. The date is given in W3C format.
public getVat(int $locationId, int $countryId, string $startedAt = null):Vat
Parameters
int $locationId
int $countryId
string $startedAt
public findVat(int $page = 1, int $itemsPerPage = \Plenty\Modules\Accounting\Vat\Models\Vat::ITEMS_PER_PAGE, array $relations = [], array $columns = []):array

List VAT configurations

Parameters
int $page The page to be returned. If no page is specified, the first page will be returned.
int $itemsPerPage The number of items per page. If not given, the model's default number will be used.
array $relations The relations to load with the VAT object. The relations available are "location" and "country".
array $columns The columns to load in the response
public findVatByLocationId(int $locationId, array $relations = [], array $columns = []):array

List VAT configurations for an accounting location

Parameters
int $locationId The ID of the accounting location
array $relations The relations to load with the VAT object. The relations available are "location" and "country".
array $columns The columns to load in the response
public findVatByLocationIdAndCountry(int $locationId, int $countryId, array $relations = [], array $columns = []):array

List VAT configuration for a country of delivery

Parameters
int $locationId The ID of the accounting location
int $countryId The ID of the country of delivery
array $relations The relations to load with the VAT object. The relations available are "location" and "country".
array $columns The columns to load in the response.
public clearCriteria():void

Resets all Criteria filters by creating a new instance of the builder object.

public applyCriteriaFromFilters():void

Applies criteria classes to the current repository.

public setFilters(array $filters = []):void

Sets the filter array.

Parameters
array $filters
public getFilters():void

Returns the filter array.

public getConditions():void

Returns a collection of parsed filters as Condition object

public clearFilters():void

Clears the filter array.

VatServiceContract

Provides methods for a quick search of VAT fields, VAT rates and VAT names of a specific VAT configuration.

Namespace

Plenty\Modules\Accounting\Vat\Contracts

Methods

public getVatField(Vat
 $vat, float $vatRate):int

Get the VAT field for a VAT rate.

Parameters
Vat $vat The VAT configuration of a country
float $vatRate The VAT rate
public getVatRate(Vat
 $vat, int $vatField):float

Get the VAT rate for a VAT field.

Parameters
Vat $vat The VAT configuration of a country
int $vatField The VAT field
public getVatName(Vat
 $vat, int $vatField):string

Get the name of a VAT field.

Parameters
Vat $vat The VAT configuration of a country
int $vatField The VAT field

Exceptions

VatException

Class VatException

Namespace

Plenty\Modules\Accounting\Vat\Exceptions

Models

Vat

The VAT model contains the complete VAT configuration in plentymarkets. The VAT configuration is based on 4 VAT rates. A VAT configuration always belongs to an accounting location. The accounting location is in a specified country and is assigned to a client. One accounting location can have several VAT configurations, but only one is active at a time. Which one is active depends on the startedAt date. This also means that only one VAT number is active per accounting location.

Namespace

Plenty\Modules\Accounting\Vat\Models

Properties

Type Name Description
int id The ID of the VAT configuration. A VAT configuration includes 4 VAT rates
int countryId The ID of the country that the VAT configuration belongs to
string taxIdNumber The tax id number of VAT configuration.
startedAt The date when the VAT configuration went into effect
invalidFrom The date when the VAT configuration should not be used any more
int locationId The ID of the location
string marginScheme Specifies the tax rate that is used, when the margin scheme is applied
bool isRestrictedToDigitalItems Flag that indicates if the VAT configuration is used only applied to digital goods or not. True= The VAT set is only applied to digital goods. False = The VAT set is applied to all types of goods.
bool isStandard Flag that indicates if the VAT configuration is the standard VAT configuration for the location
createdAt The date at which the VAT configuration was created.
updatedAt The date that the VAT configuration was last updated.
AccountingLocation location The accounting location that the VAT configuration belongs to. Each accounting location is assigned to a country and only one accounting location is allowed per country.
Country country The country that the VAT configuration belongs to
array vatRates The VAT rates of a VAT configuration

Methods

public toArray()

Returns this model as an array.

VatRate

The VAT rate model is always associated with a VAT configuration and contains the ID, name and percentage of a VAT rate. Each VAT configuration can have 4 rates.

Namespace

Plenty\Modules\Accounting\Vat\Models

Properties

Type Name Description
int id The ID of the VAT rate
float vatRate The percentage of the VAT rate, e.g. 19.00 for 19 %
string name The name of a VAT rate

Methods

public toArray()

Returns this model as an array.