InvoiceService

This service is used to get information about outgoing orders and invoices, as well as saving new or existing outgoing orders/invoices. This is done through the GetInvoices (opens new window) and SaveInvoices (opens new window) methods.

InvoiceService (opens new window)
InvoiceService WSDL (opens new window)

Data Types

Guides

Retrieve Invoices

This method is used to get InvoiceOrder data. You need to specify InvoiceReturnProperties and rowReturnProperties in order to control what data you get in return. The available Search Parameters are: CustomerIds, OrderIds, InvoiceIds, OrderStates and ChangedAfter. If you wish to get a complete list of all invoices available please use the GetOrderSyncList method.

Below is a simple XML example for getting InvoiceOrder data:

<?xml version="1.0" encoding="utf-8"?>
    <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
      <soap:Body>
        <GetInvoices xmlns="http://24sevenOffice.com/webservices">
          <searchParams>
            <CustomerIds>
              <int>1</int>
            </CustomerIds>
          </searchParams>
          <invoiceReturnProperties>
            <string>OrderId</string>
            <string>CustomerId</string>
            <string>CustomerName</string>
            <string>Addresses</string>
            <string>OrderStatus</string>
            <string>DateOrdered</string>
            <string>OurReference</string>
            <string>YourReference</string>
            <string>ReferenceNumber</string>
            <string>InvoiceRows</string>
          </invoiceReturnProperties>
          <rowReturnProperties>
            <string>ProductId</string>
            <string>RowId</string>
            <string>Name</string>
            <string>Quantity</string>
            <string>Type</string>
            <string>Price</string>
          </rowReturnProperties>  
        </GetInvoices>
      </soap:Body>
    </soap:Envelope>

Retrieve all invoice and order data

If you wish to do a complete sync you have to use the GetOrderSyncList method. This method takes either a ChangedAfter or RegisteredAfter search parameter and returns an array of OrderIds. Based on this list you can make requests to GetInvoices with up to 1000 OrderIds per request.

TIP

Trying to get all invoice data directly through GetInvoices and a date search parameter set way back in time will often result in timeouts and server errors, putting uneccessary load on your servers and making your integration less efficient.

Save Invoices

This method is used to save and update orders and invoices in the 24SevenOffice system. Please note that it is not possible to change any properties of an order that is marked as Invoiced (i.e. an invoice), only orders may be updated. If you wish to update any of the InvoiceOrder properties, you simply have to specify the OrderId and the CustomerId and your changes. The CustomerId have be to be a valid Id on the 24SevenOffice client. You can get Customer data and create new Customers with the CompanyService.

If you only provide a CustomerId when creating an InvoiceOrder, customer data like Name, Addresses etc, will be filled in automatically. If you set one Address in Addresses you have to set all of them. In other words if you specify the Delivery address, the Invoice address won't be automatically set anymore.

TIP

Please note that OrderStatus will be set to the default status Web if it is not set when updating.

Below is a simple XML example of an order with status Offer:

<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
      <soap:Body>
        <SaveInvoices xmlns="http://24sevenOffice.com/webservices">
          <invoices>
            <InvoiceOrder>
              <CustomerId>1</CustomerId>
              <OrderStatus>Offer</OrderStatus>
              <InvoiceRows>
                <InvoiceRow>
                  <ProductId>1</ProductId>
                  <Price>1.00</Price>
                  <Name>Test</Name>
                  <Quantity>1.00</Quantity>
                </InvoiceRow>
              </InvoiceRows>
            </InvoiceOrder>
          </invoices>
        </SaveInvoices>
      </soap:Body>
    </soap:Envelope>

This will create an Order in the 24SevenOffice system, but this is not yet an invoice. Most OrderStatuses will create an order. If you wish to create an invoice, set the OrderStatus to Invoiced. Orders are freely editable, but once you've created an invoice it cannot be changed or updated (with the exception of changing some reference values with the UpdateInvoices method).

After you have created a new InvoiceOrder, the OrderId will be part of the response from the API. If you set the OrderStatus to Invoiced you will get an InvoiceId in the response as well. Any updates of orders are generally done with SaveInvoices.

Set VAT rate for an invoice

In 24SevenOffice the VAT rate is connected to different types of sale. We highly recommend using these TypeGroups rather than trying to set the VAT directly on InvoiceRows in order to ensure consistent accounting and to ensure that relations between VAT and accounts are maintained.

In the most basic cases, you create an order and want the whole order to be invoiced with 0% VAT because it is e.g. a foreign sale. In these cases you set the TypeOfSaleId to the proper TypeGroup Id. You retrieve the TypeOfSaleId from the GetTypeGroupList method in our ClientService. Congratulations, you've created an InvoiceOrder with 0% VAT.

Should you need to set VAT for each individual InvoiceRow you have to set the correct Id here has well. On the InvoiceRow level this Id is called TypeGroupId and not TypeOfSaleId.

If using TypeGroups doesn't cover your needs you can also set the VAT rate on each InvoiceRow through the TaxSettings object. In order to do this you have to populate the three TaxSettings properties: TaxAccount, TaxCode and TaxRate. You'll get these values with a request to GetTaxCodeList (opens new window). This method will return a list of TaxCodeElements and the mapping for TaxSettings is as follows:

TaxCodeElement	TaxSettings
AccountNo	TaxAccount
TaxId	TaxCode
TaxRate	TaxRate

Please note that the user interface displays the TaxNo, while the API uses the TaxId. So if an accountant wishes to use TaxNo 5, you would have to set the corresponding TaxId that you retrieve from GetTaxCodeList (opens new window). The API does not restrict mixing e.g. TaxCodes and TaxRates, but it is wise to use the values that are provided by the system.

You can only apply TaxSettings to InvoiceRows, this cannot be set once for the entire InvoiceOrder.

Set an invoice as paid

Please note that this only applies when initially creating an invoice. If you wish to update an invoice with a payment at a later time, you have to use our PaymentService.

A typical scenario is when a user buys items online and pays for them with PayPal, credit card etc. In this case you have to set the following properties on the InvoiceOrder:

• OrderStatus (Invoiced)
• Paid (datetime)
• PaymentMethodId (int), see GetPaymentMethods (opens new window).
• PaymentAmount (decimal)
• DateInvoiced (datetime)

With these properties set, the newly created invoice will automatically be marked as paid in 24SevenOffice.

Create a rest order

As with any general update of an invoice row, you need to make sure that all properties that matter to you are set. For example if you have changed the Price of a product from the default price, you must specify the value of this property when doing an update.

TIP

Please note: The system will only generate a rest order if the OrderStatus is set to Invoiced, OrderState_Sent, CollectingOrder or InvoicedCashAccount.

WARNING

Also note: You have to enable resting in the Invoice Settings

The following properties concern quantity:
Quantity: This is the amount of a given product
QuantityOrdered: The total quantity that was ordered of a given product
QuantityRest: This is set when creating a rest order. When getting this property it is set to its default: -1
QuantityDelivered: The quantity that was delivered of a given product

Let’s say you have an invoice row with a Quantity of 10. You can only deliver 4, so you would then set the following values:

<InvoiceRow>
	<RowId>YOUR ROWID</RowId>
	<ChangeState>Edit</ChangeState>
	<ProductId>1</ProductId>
	<Price>1.00</Price>
	<Name>Rest Order Test</Name>
	<Quantity>10.00</Quantity>
	<QuantityRest>6.00</QuantityRest>
</InvoiceRow>

This will give you the following values on your order:

• Quantity: 4
• QuantityOrdered: 10
• QuantityRest: -1 (the default value, QuantityRest is only used for setting values)
• QuantityDelivered: 0

A new order will also be created with the following values. This is the rest order:

• Quantity: 6
• QuantityOrdered: 10
• QuantityRest: -1 (again, the default value)
• QuantityDelivered: 4

Create a credit note

In order to create a credit note, you must create a new invoice that has the negative amount of the original invoice that is to be credited. You can easily credit an invoice by inserting the same invoice rows but with negative amounts. So an invoice with an invoice row where amount is 10 and price is set to 100 would be credited in a new invoice by setting amount to -10 and price to 100. You can also set the ReferenceInvoiceId and ReferenceOrderId as references to the invoice that is being credited. It is also common to add a text line in the invoice rows of the credit note with information for the customer about which invoice is being credited.

TIP

Please note that creating a credit note through the APIs will not link the credit note and the invoice, this has to be done manually in our web interface.

Set accrual date and period

You can specify accural for the entire invoice or for individual invoice rows. In both cases you have to set the AccrualDate and the AccuralLength. The AccrualDate determines the start of the accrual and AccrualLength specifies the amount of months the accrual should be divided over.

Set invoice distribution template

You can create several templates in the invoice module that can be used when distributing your invoice. In order to set an invoice template you have to get the list of invoice templates with the GetInvoiceTemplates (opens new window) method. The method returns a list of invoice templates of the current client and you can use the Id (GUID) you wish to use to set the InvoiceTemplateId of an InvoiceOrder.

Invoice Distribution

The properties Distributor and DistributionMethod are used to control how an invoice is distributed. Please see the following table for details:

Distributor	DistributionMethod	Result
Default	Unchanged	If this is a new InvoiceOrder the new Distribution System is used. If this is an update to an existing order previous settings are retained.
Auto	Unchanged	InvoiceOrder is processed in the new Distribution System, regardless of whether this is an update or a new InvoiceOrder.
Default/Auto	Print	Automatic Print Distribution
Default/Auto	Email	Automatic Email Distribution
Default/Auto	ElectronicInvoice	Automatic ElectronicInvoice Distribution
Manual	N/A (just use Default)	Manual Distribution

Invoice Rows

If you are doing changes to any InvoiceOrder rows you need to set the ChangeState property as well with any of the following values: Add, Edit or Delete. In the cases of Editing or Deleting an InvoiceRow you also need to specify the RowId. This is an Id set by the 24SevenOffice system and not something you specify, if you wish to control the order of invoicerows you must use the SequenceNumber property.

For other details, please see Invoice Row Data Types

Updating invoice rows

If you wish to update an existing invoice row, you must specify at least the RowId and the ProductId.

TIP

Please note that if you do not specify a row property (e.g. Price) the property will be set to the default price for the specified product.

So if you want to update the quantity in an invoice row, you have to specify the RowId, the ProductId and the Quantity, but also e.g. the Name, Price etc, if these values have been changed from the default values of the product.

Adding invoice rows to an existing Order

When you are creating a brand new InvoiceOrder through the API, any InvoiceRows will automatically be added as long as all the required properties are set. However, if you are adding InvoiceRows to an existing order, the ChangeState must be explicitly set to Add. It is important to take notice of this, since the API response will contain any InvoiceRows that where part of your response, regardless of whether the Add ChangeState was set or not. This can be confusing since the response seemingly confirms that the rows where added, but only rows with the proper ChangeState will be processed by the API.

Specifying the order of invoice rows

If you wish to control the order of invoicerows you must use the SequenceNumber property.

Set text lines in invoice rows

In order to add text lines to an invoice row, you set the Type of an invoice row to Text.

Methods

Method	Input type	Return type	Description
GetInvoices (opens new window)	searchParams	InvoiceOrder	Gets a list of invoices and orders based on search parameters. You have to specify which properties you want returned in both the InvoiceOrder-object and the InvoiceRow-objects.
SaveInvoices (opens new window)	InvoiceOrder[]	InvoiceOrder[]	Saves an array of invoices and returns them with their id (if new) or an APIException if an error happened. Please note that it is not possible to submit any changes to InvoiceOrders with OrderStatus ‘Invoiced’. When saving changes to existing InvoiceOrder rows please note that the ChangeState property needs to be set on the affected InvoiceRows.
UpdateInvoices (opens new window)	InvoiceOrder[]	InvoiceOrder[]	Updates an array of invoices. Valid update properties: InvoiceTitle, ReferenceNumber
GetInvoiceTemplates (opens new window)	-	TemplateModel[]	Gets a list of all Invoice Templates
GetDeliveryMethods (opens new window)	-	DeliveryMethod[]	Gets a list of all Delivery Methods
GetPaymentMethods (opens new window)	-	PaymentMethod[]	Gets a list of all Payment Methods
GetInvoiceDocument (opens new window)	Parameters	byte[]	Gets an Invoice PDF
GetOrderSyncList (opens new window)	syncParams	int[]	Gets a list of OrderIds. This is useful when getting ALL the data for inital syncs between integrations. The method returns an integer array that can be used to get batches of up to 1000 InvoiceOrders at a time from GetInvoices.