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 and SaveInvoices methods.

InvoiceService
InvoiceService WSDL

Data Types

GetInvoices

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 you must use the ChangedAfter parameter and set the date back to your desired time range.

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>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

SaveInvoices

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 has be to be a valid Id on the 24SevenOffice client. You can get Customer data and create new Customers with the CompanyService.

TIP

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

Creating a basic invoice or order

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>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

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 or Invoices are generally done with SaveInvoices.

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.

Specifying the order of invoice rows

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

How to set an invoice as paid

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
  • PaymentAmount (decimal)
  • InvoiceDate (datetime)

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

How to 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.

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

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>
1
2
3
4
5
6
7
8
9

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

Creating 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.

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 Any Manual Distribution

Methods

Method Input type Input name Return type Description
GetInvoices InvoiceSearchParameters, String[], String[] searchParams, invoiceReturnProperties, rowReturnProperties 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 InvoiceOrder[] invoices 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 InvoiceOrder[] invoices InvoiceOrder[] Updates an array of invoices. Valid update properties: InvoiceTitle, ReferenceNumber
GetInvoiceTemplates TemplateModel[] Gets a list of all Invoice Templates
GetDeliveryMethods DeliveryMethod[] Gets a list of all Delivery Methods
GetPaymentMethods PaymentMethod[] Gets a list of all Payment Methods
GetInvoiceDocument InvoiceDocumentSearchParameters Parameters byte[] Gets an Invoice PDF
GetOrderSyncList InvoiceSyncParameters Parameters 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.