How Tos

<page>
<metadata>
<title>How Tos</title>
<path>/businessnxtapi/examples/howto</path>
<kind>section</kind>
<description>Guides and best practices for integrating with the Business NXT GraphQL API, including creating orders and managing documents.</description>
<lastmod>2026-07-10T12:31:03&#43;03:00</lastmod>
</metadata>
<content>
# How Tos

Guides and best practices for integrating with the Business NXT GraphQL API, including creating orders and managing documents.


We recognize that having learned GraphQL API does not mean you are able to write integrations without further help. Although tools such as GraphiQL, Postman, and Insomnia allow you to browse the schema and discover the Business NXT model and operations with it, writing code to handle your data requires further knowledge.

In this section, we provide a series of guides to help you perform some common business operations.

- [How to create and finish an order](order.md)
- [How to get customer prices](customerprices.md)
- [How to add an attachment to an order](orderattachments.md)
- [How to invoice an order](invoice_order.md)
- [How to create and update a batch](batch.md)
- [How to add a document to a voucher](voucherdocument.md)
- [How to read text from the Text table](texts.md)</content>
</page><page>
<metadata>
<title>How to create and finish an order</title>
<path>/businessnxtapi/examples/howto/order</path>
<kind>page</kind>
<description>Guide to creating, adding lines, and finishing an order using GraphQL mutations. Includes field requirements, example queries, and responses for each step.</description>
<lastmod>2026-07-10T12:31:03&#43;03:00</lastmod>
</metadata>
<content>
# How to create and finish an order

Guide to creating, adding lines, and finishing an order using GraphQL mutations. Includes field requirements, example queries, and responses for each step.


You need to perform the following GraphQL requests, in this order:

## 1. Create a new order and lines

The minimum information for the order head you must provide is:

| Field | Type | Description |
| ----- | ---- | ----------- |
| `orderDate` | int | The date of the order. An integer in the form `yyyymmdd`. For instance, 23 March 2022, is 20220323. |
| `customerNo` | int | The number identifying the customer in Business NXT. (Do not confuse this with the Visma.net customer number!) |

The minimum information you must provide for each order line is:

| Field | Type | Description |
| ----- | ---- | ----------- |
| `productNo` | int | The number identifying the product in the system. |
| `quantity` | int | The quantity of items that you want to add. |

Use the following mutation to create an order and its lines:

```graphql { title = "Query" }
mutation create_order($cid : Int!,
                      $cno : Int!,
                      $date : Int,
                      $pno1 : String,
                      $pno2 : String)
{
   useCompany(no : $cid)
   {
      order_create(values:[
      {
         orderDate : $date
         customerNo : $cno
         orderLines : [
            {
               productNo : $pno1
               quantity : 1
            },
            {
               productNo : $pno2
               quantity : 2
            }
         ]
      }])
      {
         affectedRows
         items
         {
            orderNo
            orderDate

            orderLines : joindown_OrderLine_via_Order
            {
               items
               {
                  lineNo
                  productNo
                  quantity
                  priceInCurrency
               }
            }
         }
      }
   }
}
```

```graphql { title = "Result" }
{
  "data": {
    "useCompany": {
      "order_create": {
        "affectedRows": 1,
        "items": [
          {
            "orderNo": 439,
            "orderDate": 20250917
            "orderLines": {
              "items": [
                {
                  "lineNo": 1,
                  "productNo": "HW1",
                  "quantity": 1,
                  "priceInCurrency": 100
                },
                {
                  "lineNo": 2,
                  "productNo": "AGG4",
                  "quantity": 2,
                  "priceInCurrency": 75
                }
              ]
            }
          }
        ]
      }
    }
  }
}
```

## 2. Finishing an order

The minimum information you need to finish an order is the order number.

Use a mutation with the `order_processings` field to execute a processing on an order. To finish the order, use the `finish` field:

```graphql { title = "Query" }
mutation finish_order($cid : Int!,
                      $ono : Int!)
{
  useCompany(no : $cid)
  {
    order_processings
    {
      finish(filter: {orderNo:{_eq : $ono}})
      {
        succeeded
        items
        {
          handledOrderLine
          {
            lineNo
            finishedNow
          }
        }
      }
    }
  }
}
```

```graphql { title = "Result" }
{
  "data": {
    "useCompany": {
      "order_processings": {
        "finish": {
          "succeeded": true,
          "items": [
            {
              "handledOrderLine": [
                {
                  "lineNo": 1,
                  "finishedNow": 1
                },
                {
                  "lineNo": 2,
                  "finishedNow": 2
                }
              ]
            }
          ]
        }
      }
    }
  }
}
```

### Finishing parameters

The `finish` processing has a parameter called `finishType` that is an integer defining what the processing should do.
The implicit value is 0 which means the whole order should be finished. This is what we have seen in the previous example, where the argument was missing, therefore its default value was used.

The possible values for `finishType` are:

| Value | Description |
| ----- | ----------- |
| 0 | Finish the whole order. |
| 1 | Finish the articles specified by their barcode. |
| 2 | Finish the articles specified by their product number. |
| 3 | Finish the articles specified by their `TransactionInformation1` field. |

Alternatively, you can use the `finishTypeAsEnum` field, that enables you to use a enumeration value, instead of a numerical one. The possible values are:

| Name | Value |
| ---- | ----- |
| WholeOrder | 0 |
| Barcode | 1 |
| ProductNumber | 2 |
| TransactionInformation1 | 3 |

When `finishType` has any other value than 0, then you need to provide the additional arguments using the `group` parameter. This is a dictionary of key-value pairs, where the key is the bar code, product number, or the `TransactionInformation1` value of a product, and value is the quantity to finish (remove from the order).

```graphql { title = "Query" }
mutation finish_order($cid : Int!,
                      $ono : Int!)
{
  useCompany(no : $cid)
  {
    order_processings
    {
      finish(
        args : {
          finishTypeAsEnum : ProductNumber
          group : [
            {key: "HW1",  quantity: 2},
            {key: "AGG4", quantity: 5}
          ]
        },
        filter: {orderNo:{_eq : $ono}}
      )
      {
        succeeded
        items
        {
          handledOrderLine
          {
            lineNo
            finishedNow
          }
        }
      }
    }
  }
}
```

```graphql { title = "Result" }
{
  "data": {
    "useCompany": {
      "order_processings": {
        "finish": {
          "succeeded": true,
          "items": [
            {
              "handledOrderLine": [
                {
                  "lineNo": 1,
                  "finishedNow": 2
                },
                {
                  "lineNo": 2,
                  "finishedNow": 5
                }
              ]
            }
          ]
        }
      }
    }
  }
}
```

## Alternatives for creating an order and order lines

The _obsolete_ way of creating an order and its lines is to do it in two separate requests. First, you create the order head, and then you add the order lines.

### 1. Two separate requests

Use a mutation with the `order_create` field to add a new order:

```graphql { title = "Query" }
mutation create_order($cid : Int!,
                      $cno : Int!,
                      $date : Int)
{
  useCompany(no : $cid)
  {
    order_create(values:[{
      orderDate : $date
      customerNo : $cno
    }])
    {
      affectedRows
      items
      {
        orderNo
        orderDate
      }
    }
  }
}
```

```graphql { title = "Result" }
{
  "data": {
    "useCompany": {
      "order_create": {
        "affectedRows": 1,
        "items": [
          {
              "orderNo": 439,
              "orderDate": 20220401
          }
        ]
      }
    }
  }
}
```

From the result, you must use the `orderNo` to add order lines. Then, use a mutation with the `orderLine_create` field to add one or more order lines:

```graphql { title = "Query" }
mutation create_order_line($cid : Int!,
                           $ono : Int!,
                           $pno1 : String,
                           $pno2 : String)
{
  useCompany(no : $cid)
  {
    orderLine_create(values:[
      {
        orderNo : $ono
        productNo : $pno1
        quantity : 1
      },
      {
        orderNo : $ono
        productNo : $pno2
        quantity : 2
      },
    ])
    {
      affectedRows
      items
      {
        lineNo
      }
    }
  }
}
```

```graphql { title = "Result" }
{
  "data": {
    "useCompany": {
      "orderLine_create": {
        "affectedRows": 2,
        "items": [
          {
            "lineNo": 1
          },
          {
            "lineNo": 2
          }
        ]
      }
    }
  }
}
```

### 2. One request using the @export directive

You can create both an order and its order lines with a single request, using the `@export` directive. This [directive](../../apireference/features/directives.md#the-export-directive) allows you to capture the value of an evaluated field into a variable that can be used later in the query.

```graphql { title = "Query" }
mutation create_order_and_line($cid : Int!,
                               $cno : Int!,
                               $date : Int
                               $pno1 : String,
                               $pno2 : String,
                               $ono : Int = 0)
{
  useCompany(no : $cid)
  {
    # create the order first
    order_create(values:[{
      orderDate : $date
      customerNo : $cno
    }])
    {
      affectedRows
      items
      {
        # capture the value of the orderNo field
        # into the ono variable
        orderNo @export(as: "ono")
        orderDate
      }
    }

    # create the order lines
    orderLine_create(values:[
      {
        orderNo : $ono
        productNo : $pno1
        quantity : 1
      },
      {
        orderNo : $ono
        productNo : $pno2
        quantity : 2
      },
    ])
    {
      affectedRows
      items
      {
        orderNo
        lineNo
      }
    }
  }
}
```

```graphql { title = "Result" }
{
  "data": {
    "useCompany": {
      "order_create": {
        "affectedRows": 1,
        "items": [
          {
              "orderNo": 440,
              "orderDate": 20221122
          }
        ]
      },
      "orderLine_create": {
        "affectedRows": 2,
        "items": [
          {
            "orderNo": 440,
            "lineNo": 1
          },
          {
            "orderNo": 440,
            "lineNo": 2
          }
        ]
      }
    }
  }
}
```
</content>
</page><page>
<metadata>
<title>How to get customer prices</title>
<path>/businessnxtapi/examples/howto/customerprices</path>
<kind>page</kind>
<description>Guide to fetching the customer prices for an product using GraphQL mutations. Includes example queries, and responses for each step.</description>
<lastmod>2026-07-10T12:31:03&#43;03:00</lastmod>
</metadata>
<content>
# How to get customer prices

Guide to fetching the customer prices for an product using GraphQL mutations. Includes example queries, and responses for each step.


There is no direct way to fetch product customer prices but it can be achieve as follows:

- create an order
- add lines with the desired products
- read the `priceInCurrency`
- delete the order (and lines)

This can be achieved with a single request that also avoids the last step, by using temporary rows (defined with the `temporary : true`).

```graphql { title = "Query" }
mutation get_customer_price($cid : Int!, $customer : Int, $prod : String)
{
   useCompany(no : $cid)
   {
      order_create(
         values:[
            {
               customerNo : $customer,
               orderLines : [
                  { productNo : $prod, quantity : 1 },
               ]
            }
         ],
         temporary : true
      )
      {
         affectedRows
         items
         {
            customerNo
            orderLines: joindown_OrderLine_via_Order
            {
               items
               {
                  productNo
                  quantity
                  priceInCurrency
               }
            }
         }
      }
   }
}
```

```graphql { title = "Result" }
{
   "data": {
      "useCompany": {
         "order_create": {
            "affectedRows": 1,
            "items": [
               {
                  "customerNo": 10001,
                  "orderLines": {
                     "items": [
                        {
                           "productNo": "1001",
                           "quantity": 1,
                           "priceInCurrency": 995
                        }
                     ]
                  }
               }
            ]
         }
      }
   }
}
```
</content>
</page><page>
<metadata>
<title>How to add an attachment to an order</title>
<path>/businessnxtapi/examples/howto/orderattachments</path>
<kind>page</kind>
<description>Instructions on adding attachments to orders using GraphQL, including setting specific document types and handling file size limitations.</description>
<lastmod>2026-07-10T12:31:03&#43;03:00</lastmod>
</metadata>
<content>
# How to add an attachment to an order

Instructions on adding attachments to orders using GraphQL, including setting specific document types and handling file size limitations.


You can add an attachment to an order by runnning the `AddAttachment` processing on the `Order` table.

The following query adds an attachment to an existing order:

```graphql
mutation upload_invoice_attachment(
        $cid: Int!,
        $orderNo: Int!,
        $fileName: String!,
        $description: String!,
        $data: String!)
{
  useCompany(no: $cid) {
    order_processings {
      addAttachment(
        filter: { orderNo: { _eq: $orderNo } },
        args: { 
           description: $description, 
           fileName: $fileName, 
           fileBytes: $data,
           sendWithInvoicesAndCreditNotes : 1
        }
      )
      {
        succeeded
      }
    }
  }
}
```

> [!NOTE]
>
> The content of the attachment must be provided as a base64 encoded string.

The precence of the `sendWithInvoicesAndCreditNotes : 1` argument will set the order attachment processing to `Invoices/credit notes`. You can see this in the front-end, when you look at the `Order attachment processing` column of the `Order attachment` table.

![Order attachment processing](../order_attachment_processing.png)

If you want to set any of the other available values, such as `Pick lists` or `Packing slips`, then you must use the `sendWithDocumentTypes` parameter instead. The following table shows the available values for this parameter:

| Value | Description |
| ----- | ----------- |
| 1 | Invoices/credit notes |
| 2 | Consignment notes |
| 4 | Packing slips |
| 8 | Pick lists |
| 16 | Order confirmations |
| 32 | Quotations |
| 64 | Purchase orders |
| 128 | Inquiries |
| 256 | Production orders |
| 512 | Order prints |
| 1024 | Approval requests |

The following example shows how to set the `sendWithDocumentTypes` parameter to `Packing slips`:

```graphql
mutation upload_packing_slip_attachment(
        $cid: Int!,
        $orderNo: Int!,
        $fileName: String!,
        $description: String!,
        $data: String!)
{
  useCompany(no: $cid) {
    order_processings {
      addAttachment(
        filter: { orderNo: { _eq: $orderNo } },
        args: { 
           description: $description, 
           fileName: $fileName, 
           fileBytes: $data,
           sendWithDocumentTypes : 4
        }
      )
      {
        succeeded
      }
    }
  }
}
```

> [!NOTE]
>
> Beware there is a limit to the raw size of a request. Currently, this is set at 15MB. This limit may be prone to future changes.
</content>
</page><page>
<metadata>
<title>How to invoice an order</title>
<path>/businessnxtapi/examples/howto/invoice_order</path>
<kind>page</kind>
<description>Guide on invoicing orders using GraphQL mutation. Includes example query, result, and parameter descriptions for generating invoices and credit note reports.</description>
<lastmod>2026-07-10T12:31:03&#43;03:00</lastmod>
</metadata>
<content>
# How to invoice an order

Guide on invoicing orders using GraphQL mutation. Includes example query, result, and parameter descriptions for generating invoices and credit note reports.


To invoice an order, you must first finish the order. You can run the `invoicesAndCreditNotes` report on the `Order` table in order to invoice an order, as shown in the following example:

```graphql { title = "Query" }
mutation invoice_order($cid : Int!,
                      $ono : [Int]!)
{
  useCompany(no : $cid)
  {
    order_reports
    {
      invoicesAndCreditNotes(
        filter:{orderNo :{_in : $ono}},
        returnDocuments : true,
        printDestination : PRINT_TO_PDF,
        approval : true
      )
      {
        succeeded
        documents
        {
          name
          content
          attachments
          {
            name
            content
          }
        }
      }
    }
  }
}
```

```graphql { title = "Result" }
{
  "data": {
    "useCompany": {
      "order_reports": {
        "invoicesAndCreditNotes": {
          "succeeded": true,
          "documents": [
            {
              "name": "1000013.pdf",
              "content": "JVBERi0xLjQKJdD...",
              "attachments": []
            }
          ]
        }
      }
    }
  }
}
```

The parameters have the following meaning:

| Parameter | Description |
| --------- | ----------- |
| `filter` | The filter to apply to the report. In this case, we are filtering by the order number (one or more orders). |
| `returnDocuments` | If set to `true`, the report will return the invoice document. |
| `printDestination` | The destination where the invoice will be printed. In this case, we are printing to a PDF file. |
| `approval` | It updates the tables when set to `true` (the default value). Set to `false` to only preview results. |

> [!TIP]
>
> The content of the returned documents (and attachments) is base64-encoded. You must decode it to get the original file.
</content>
</page><page>
<metadata>
<title>How to create and update a batch</title>
<path>/businessnxtapi/examples/howto/batch</path>
<kind>page</kind>
<description>Guide on creating and updating a batch using GraphQL. Includes steps for batch creation, determining voucher number, voucher creation, and batch update.</description>
<lastmod>2026-07-10T12:31:03&#43;03:00</lastmod>
</metadata>
<content>
# How to create and update a batch

Guide on creating and updating a batch using GraphQL. Includes steps for batch creation, determining voucher number, voucher creation, and batch update.


You need to perform the following GraphQL requests, in this order:

## 1. Determining the next voucher no

When creating a voucher, you need to provide a voucher number. You can determine this value by reading the `nextVoucherNo` value from the `VoucherSeries` table. To do so, you must provide the `voucherSeriesNo` which should be the same used for creating the batch.

```graphql { title = "Query" }
query read_voucher_series($cid : Int!,
                          $vsn : Int!)
{
   useCompany(no : $cid)
   {
      voucherSeries(filter :
         {
            voucherSeriesNo : {_eq: $vsn}
         }
      )
      {
         totalCount
         items
         {
            voucherSeriesNo
            name
            lastVoucherNo
            nextVoucherNo
         }
      }
   }
}
```

```graphql { title = "Result" }
{
  "data": {
    "useCompany": {
      "voucherSeries": {
        "totalCount": 1,
        "items": [
          {
            "voucherSeriesNo": 6,
            "name": "Diverse bilag",
            "lastVoucherNo": 69999,
            "nextVoucherNo": 60003
          }
        ]
      }
    }
  }
}
```

## 2. Creating a new batch and voucher

The minimum information you need to provide for creating the batch is:

| Field | Type | Description |
| ----- | ---- | ----------- |
| `valueDate` | int | The value date as an integer in the form `yyyymmdd`. For instance, 23 March 2022, is 20220323. |
| `voucherSeriesNo` | int | The number of the voucher series. |

The minimum information you need to provide in order to create a new voucher is:

| Field | Type | Description |
| ----- | ---- | ----------- |
| `voucherNo` | int | The number of the voucher. Use the `nextVoucherNo` value read previously. |
| `debitAccountNo` | int | The debit account number. |
| `creditAccountNo` | int | The credit account number. |
| `amountDomestic` | decimal | The amount value. |
| `voucherDate` | int | The date of the voucher. |
| `valueDate` | int | The value date of the voucher. |

```graphql { title = "Query" }
mutation create_batch_and_voucher($cid : Int!,
                                  $cno : Int!,
                                  $vno : Int!,
                                  $vdt : Int!,
                                  $valuedt : Int!)
{
   useCompany(no : $cid)
   {
      batch_create(values:[
      {
         valueDate : $valuedt

         vouchers : [
            {
               voucherNo : $vno
               debitAccountNo : 1930
               creditAccountNo : $cno
               customerNo : $cno
               amountDomestic : 100
               voucherDate : $vdt
               valueDate : $valuedt
            }
         ]
      }])
      {
         affectedRows
         items 
         {
            batchNo
            valueDate

            vouchers : joindown_Voucher_via_Batch
            {
               items
               {
                  batchNo
                  lineNo

                  voucherNo
                  customerNo
                  debitAccountNo
                  creditAccountNo
                  amountDomestic
                  voucherDate
                  valueDate
               }
            }
         }
      }
   }
}
```

```graphql { title = "Result" }
{
  "data": {
    "useCompany": {
      "batch_create": {
        "affectedRows": 1,
        "items": [
          {
            "batchNo": 1002,
            "valueDate": 20251015

            "vouchers": {
              "items": [
                {
                  "batchNo": 1002,
                  "lineNo": 1,
                  "voucherNo": 60003,
                  "customerNo": 10001,
                  "debitAccountNo": 1930,
                  "creditAccountNo": 10001,
                  "amountDomestic": 100,
                  "voucherDate": 20250917,
                  "valueDate": 20251015
                }
              ]
            }
          }
        ]
      }
    }
  }
}
```

### Alternatives for creating a batch and voucher

The _obsolete_ way of creating a batch and vouchers is to do it in two separate requests. First, you create the batch, and then you add the vouchers.

#### 1. Two separate requests

Use a mutation with the `batch_create` field to create a new batch:

```graphql { title = "Query" }
mutation create_batch($cid : Int!,
                      $vsn : Int!,
                      $valuedt : Int!)
{
   useCompany(no : $cid)
   {
      batch_create(values:[
         {
            voucherSeriesNo : $vsn
            valueDate : $valuedt
         }
      ])
      {
         affectedRows
         items
         {
            batchNo
            valueDate
         }
      }
   }
}
```

```graphql { title = "Result" }
{
  "data": {
    "useCompany": {
      "batch_create": {
        "affectedRows": 1,
        "items": [
          {
            "batchNo": 1002,
            "valueDate": 20220415
          }
        ]
      }
    }
  }
}
```

You must read and store the `batchNo` in order to use it for creating a voucher. Then, use a mutation with the `voucher_create` field to create a new voucher:

```graphql { title = "Query" }
mutation create_voucher($cid : Int!,
                        $bno : Int!,
                        $cno : Int!,
                        $vno : Int!,
                        $vdt : Int!,
                        $valuedt : Int!)
{
   useCompany(no : $cid)
   {
      voucher_create(values: [
         {
            batchNo : $bno
            voucherNo : $vno
            debitAccountNo : 1930
            creditAccountNo: $cno
            amountDomestic : 100
            voucherDate : $vdt
            valueDate : $valuedt
         }
      ])
      {
         affectedRows
         items
         {
            batchNo
            voucherNo
            voucherDate
            valueDate
         }
      }
}
}
```

```graphql { title = "Result" }
{
  "data": {
    "useCompany": {
      "voucher_create": {
        "affectedRows": 1,
        "items": [
          {
            "batchNo": 1002,
            "voucherNo": 60003,
            "voucherDate": 20220323,
            "valueDate": 20220415
          }
        ]
      }
    }
  }
}
```

#### 2. One request using the @export directive

This is possible using the [@export](../../apireference/features/directives/#the-export-directive) directive.

```graphql { title = "Query" }
mutation create_batch($cid : Int!,
                      $vsn : Int!,
                      $valuedt : Int!,
                      $cno : Int!,
                      $bno : Int! = 0)
{
   useCompany(no : $cid)
   {
      batch_create(values:[
         {
            voucherSeriesNo : $vsn
            valueDate : $valuedt
         }]
      )
      {
         affectedRows
         items
         {
            batchNo @export(as: "bno")
            valueDate
         }
      }

      voucher_create(values: [
         {
            batchNo : $bno
            voucherNo : null
            debitAccountNo : 1930
            creditAccountNo: $cno
            amountDomestic : 100
            voucherDate : null
            valueDate : $valuedt
         }
      ])
      {
         affectedRows
         items
         {
            batchNo
            voucherNo
            voucherDate
            valueDate
         }
      }
   }
}
```

```graphql { title = "Result" }
{
  "data": {
    "useCompany": {
      "batch_create": {
        "affectedRows": 1,
        "items": [
          {
            "batchNo": 1002,
            "valueDate": 20220415
          }
        ]
      },
      "voucher_create": {
        "affectedRows": 1,
        "items": [
          {
            "batchNo": 1002,
            "voucherNo": 60003,
            "voucherDate": 20220323,
            "valueDate": 20220415
          }
        ]
      }
    }
  }
}
```

### Create a new voucher with suggested voucher number

Instead of determining the next voucher number in the series you can request that the system figures out the next value for it. You can also do that for other fields, such as voucher date.
This is done with the [Suggest Feature](/businessnxtapi/apireference/schema/mutations/inserts/#suggested-values).

```graphql { title = "Query" }
mutation create_voucher($cid : Int!,
                        $bno : Int!,
                        $cno : Int!,
                        $valuedt : Int!)
{
   useCompany(no : $cid)
   {
      voucher_create(values: [
         {
            batchNo : $bno
            voucherNo : null
            debitAccountNo : 1930
            creditAccountNo: $cno
            amountDomestic : 100
            voucherDate : null
            valueDate : $valuedt
         }
      ])
      {
         affectedRows
         items
         {
            batchNo
            voucherNo
            voucherDate
            valueDate
         }
      }
   }
}
```

```graphql { title = "Result" }
{
  "data": {
    "useCompany": {
      "voucher_create": {
        "affectedRows": 1,
        "items": [
          {
            "batchNo": 1002,
            "voucherNo": 60003,
            "voucherDate": 20220323,
            "valueDate": 20220415
          }
        ]
      }
    }
  }
}
```

## 3. Updating a batch

The minimum information to update a batch is the batch number.

Use a mutation with the `batch_processings` field to execute processings on the batch table. Use the `updateBatch` field to update the batch:

```graphql { title = "Query" }
mutation update_batch($cid : Int!,
                      $bno : Int!)
{
   useCompany(no : $cid)
   {
      batch_processings
      {
         updateBatch(filter :
           {
             batchNo : {_eq : $bno}
           }
         )
         {
            succeeded
            voucherJournalNo
         }
      }
   }
}
```

```graphql { title = "Result" }
{
  "data": {
    "useCompany": {
      "batch_processings": {
        "updateBatch": {
          "succeeded": true,
          "voucherJournalNo": 193
        }
      }
    }
  }
```
</content>
</page><page>
<metadata>
<title>How to add a document to a voucher</title>
<path>/businessnxtapi/examples/howto/voucherdocument</path>
<kind>page</kind>
<description>Guide on adding a document to a voucher and transferring it to file service using GraphQL mutations. Includes example queries and notes on limitations.</description>
<lastmod>2026-07-10T12:31:03&#43;03:00</lastmod>
</metadata>
<content>
# How to add a document to a voucher

Guide on adding a document to a voucher and transferring it to file service using GraphQL mutations. Includes example queries and notes on limitations.


You can add a document to a voucher by running the the `AddNewDocument` processing on the `Voucher` table.

The following query adds a document to an existing voucher:

```graphql
mutation upload_voucher_document(
        $cid: Int!,
        $batchNo : Int!,
        $voucherNo: Int!,
        $fileName: String!,
        $description: String!,
        $data: String!)
{
  useCompany(no: $cid) {   
    voucher_processings {
      addNewDocument(
        filter: {_and:[
          {batchNo : {_eq : $batchNo}},
          {voucherNo : {_eq : $voucherNo}}
        ]},
      args: {
        fileName : $fileName,
        description : $description,
        fileBytes : $data
      })
      {
        succeeded        
      }
    }
  }
}
```

> [!NOTE]
>
> The content of the document must be provided as a base64 encoded string.

> [!NOTE]
>
> Beware there is a limit to the raw size of a request. Currently, this is set at 15MB. This limit may be prone to future changes.

## Transfering a document to the file service

Documents attached using the `Voucher.AddNewDocument` processing are stored in the database. If you want to transfer the document to the file service, you can use the `UploadToFileService` processing on the `IncomingAccountingDocumentAttachment` table, as shown in the following example:

```graphql
mutation move_attachment_to_fileservice(
   $cid: Int, 
   $fileName: String,
   $tok: String)
{
  useCompany(no: $cid)
  {
    incomingAccountingDocumentAttachment_processings
    {
      uploadToFileService(
        filter: {fileName: {_eq: $fileName}},
        args: {
          connectToken: $tok
        }
      )
      {
        succeeded
      }
    }
  }
}
```

The argument `connectToken` requires a valid Visma Connect access token. This is the same token you use to authenticate your requests to the Business NXT API.

You can execute these two processings sequentially, in a single request.

```graphql
mutation upload_voucher_document(
        $cid: Int!,
        $batchNo : Int!,
        $voucherNo: Int!,
        $fileName: String!,
        $description: String!,
        $data: String!,
        $tok: String)
{
  useCompany(no: $cid) {   
    voucher_processings {
      addNewDocument(
        filter: {_and:[
          {batchNo : {_eq : $batchNo}},
          {voucherNo : {_eq : $voucherNo}}
        ]},
      args: {
        fileName : $fileName,
        description : $description,
        fileBytes : $data
      })
      {
        succeeded        
      }
    }

    incomingAccountingDocumentAttachment_processings
    {
      uploadToFileService(
        filter: {fileName: {_eq: $fileName}},
        args: {
          connectToken: $tok
        }
      )
      {
        succeeded
      }
    }
  }
}
```

> [!NOTE]
>
> In the future, the `Voucher.AddNewDocument` processing may be updated to transfer the document to the file service directly without needing to execute the second processing explicitly.
</content>
</page><page>
<metadata>
<title>How to read text from the Text table</title>
<path>/businessnxtapi/examples/howto/texts</path>
<kind>page</kind>
<description>Learn how to query and filter text values from the Text table for various fields, including payment and delivery methods, using GraphQL.</description>
<lastmod>2026-07-10T12:31:03&#43;03:00</lastmod>
</metadata>
<content>
# How to read text from the Text table

Learn how to query and filter text values from the Text table for various fields, including payment and delivery methods, using GraphQL.


## Overview

The `Text` table contains text values for various fields from many tables. Examples are the text values for the payment method and delivery method of an order.
It is a common need to retrieve these texts. The following image shows possible values for the payment method for an order:

![Payment methods](../text_paymentmethods.png)

These values can be retrieved with a query as follows:

```graphql { title = "Query" }
query read_payment_methods($cid :Int!)
{
  useCompany(no :$cid)
  {
    text(filter:{_and : [
      {textType : {_eq : 7}},
      {languageNo : {_eq : 47}}
    ]})
    {
      totalCount
      items
      {
        textNo
        text
      }
    }
  }
}
```

```graphql { title = "Result" }
{
  "data": {
    "useCompany": {
      "text": {
        "totalCount": 10,
        "items": [
          {
            "textNo": 1,
            "text": "Kontant kasse"
          },
          {
            "textNo": 2,
            "text": "Bankkort"
          },
          {
            "textNo": 3,
            "text": "Visa"
          },
          {
            "textNo": 4,
            "text": "Master-/Eurocard"
          },
          {
            "textNo": 5,
            "text": "Am-ex"
          },
          {
            "textNo": 8,
            "text": "Tilgodelapp"
          },
          {
            "textNo": 9,
            "text": "Gavekort"
          },
          {
            "textNo": 97,
            "text": "Diverse"
          },
          {
            "textNo": 98,
            "text": "Differanse dagsoppgjør"
          },
          {
            "textNo": 99,
            "text": "Avbrutt"
          }
        ]
      }
    }
  }
}
```

## Filtering

These text values are available in multiple languages. Therefore, you need to filter by language and text type, as shown in the previous example.

The possible values for languages are the following:

| LanguageNo | Language |
| ---------- | -------- |
| 44 | English |
| 45 | Danish |
| 46 | Swedish |
| 47 | Norwegian |

The possible values for the texttype field are presented in the following table:

| Text type | Description (Identifier) |
| --------- | ----------- |
| 1 | FreeText |
| 2 | ReminderText |
| 3 | DocumentName |
| 4 | DeliveryTerms |
| 5 | DeliveryMethod |
| 6 | PaymentTerms |
| 7 | PaymentMethod |
| 8 | InformationCategory |
| 9 | District |
| 10 | Trade |
| 11 | OrderPriceGroup |
| 12 | CustomerPriceGroup1 |
| 13 | ProductPriceGroup1 |
| 14 | EmployeePriceGroup |
| 15 | PayrollRateNo |
| 16 | Unit |
| 17 | TaxAndAccountingGroup |
| 18 | AccountSet |
| 19 | ProductType1 |
| 20 | TransactionGroup1 |
| 21 | ProductPriceGroup2 |
| 22 | BudgetLineType |
| 23 | StockCountGroup |
| 24 | AssociateGrouping1 |
| 25 | AssociateGrouping2 |
| 26 | AssociateGrouping3 |
| 27 | AssociateGrouping4 |
| 28 | AssociateGrouping5 |
| 29 | AssociateGrouping6 |
| 30 | GeneralLedgerAccountGrouping1 |
| 31 | GeneralLedgerAccountGrouping2 |
| 32 | GeneralLedgerAccountGrouping3 |
| 33 | GeneralLedgerAccountGrouping4 |
| 34 | GeneralLedgerAccountGrouping5 |
| 35 | GeneralLedgerAccountGrouping6 |
| 36 | OrgUnitGrouping1 |
| 37 | OrgUnitGrouping2 |
| 38 | OrgUnitGrouping3 |
| 39 | OrgUnitGrouping4 |
| 40 | OrgUnitGrouping5 |
| 41 | OrgUnitGrouping6 |
| 42 | ProductGrouping1 |
| 43 | ProductGrouping2 |
| 44 | ProductGrouping3 |
| 45 | ProductGrouping4 |
| 46 | ProductGrouping5 |
| 47 | ProductGrouping6 |
| 48 | OrderGrouping1 |
| 49 | OrderGrouping2 |
| 50 | OrderGrouping3 |
| 51 | OrderGrouping4 |
| 52 | OrderGrouping5 |
| 53 | OrderGrouping6 |
| 54 | ProductTransactionControlStatus |
| 55 | AccountingTransactionControlStatus |
| 56 | ReportHeading |
| 57 | SumLine |
| 58 | ProductType2 |
| 59 | TransactionGroup2 |
| 60 | OrgUnitStatus |
| 61 | CapitalAssetGrouping1 |
| 62 | CapitalAssetGrouping2 |
| 63 | CapitalAssetGrouping3 |
| 64 | CapitalAssetGrouping4 |
| 65 | CapitalAssetGrouping5 |
| 66 | CapitalAssetGrouping6 |
| 67 | PaymentPriority |
| 68 | DeliveryPriority |
| 69 | AppointmentPriority |
| 70 | DayPriority |
| 71 | DocumentGroup |
| 72 | ProductPriceGroup3 |
| 73 | CustomerPriceGroup2 |
| 74 | AssociateGrouping7 |
| 75 | AssociateGrouping8 |
| 76 | AssociateGrouping9 |
| 77 | AssociateGrouping10 |
| 78 | AssociateGrouping11 |
| 79 | AssociateGrouping12 |
| 80 | GeneralLedgerAccountGrouping7 |
| 81 | GeneralLedgerAccountGrouping8 |
| 82 | GeneralLedgerAccountGrouping9 |
| 83 | GeneralLedgerAccountGrouping10 |
| 84 | GeneralLedgerAccountGrouping11 |
| 85 | GeneralLedgerAccountGrouping12 |
| 86 | CapitalAssetGrouping7 |
| 87 | CapitalAssetGrouping8 |
| 88 | CapitalAssetGrouping9 |
| 89 | CapitalAssetGrouping10 |
| 90 | CapitalAssetGrouping11 |
| 91 | CapitalAssetGrouping12 |
| 92 | OrgUnitGrouping7 |
| 93 | OrgUnitGrouping8 |
| 94 | OrgUnitGrouping9 |
| 95 | OrgUnitGrouping10 |
| 96 | OrgUnitGrouping11 |
| 97 | OrgUnitGrouping12 |
| 98 | ProductGrouping7 |
| 99 | ProductGrouping8 |
| 100 | ProductGrouping9 |
| 101 | ProductGrouping10 |
| 102 | ProductGrouping11 |
| 103 | ProductGrouping12 |
| 104 | OrderGrouping7 |
| 105 | OrderGrouping8 |
| 106 | OrderGrouping9 |
| 107 | OrderGrouping10 |
| 108 | OrderGrouping11 |
| 109 | OrderGrouping12 |
| 110 | TransactionGroup3 |
| 111 | TransactionGroup4 |
| 112 | ProductType3 |
| 113 | ProductType4 |
| 114 | AppointmentGrouping1 |
| 115 | AppointmentGrouping2 |
| 116 | AppointmentGrouping3 |
| 117 | AppointmentGrouping4 |
| 118 | AppointmentGrouping5 |
| 119 | AppointmentGrouping6 |
| 120 | AppointmentGrouping7 |
| 121 | AppointmentGrouping8 |
| 122 | AppointmentGrouping9 |
| 123 | AppointmentGrouping10 |
| 124 | AppointmentGrouping11 |
| 125 | AppointmentGrouping12 |
| 126 | PriceType |
| 127 | CreateDocument |
| 128 | CrmTexts |
| 129 | EftCurrencyCode |
| 130 | EftTaxCode |
| 131 | EftDeclarationCode |
| 132 | EftPaymentMethod |
| 133 | PriceRefundGrouping1 |
| 134 | PriceRefundGrouping2 |
| 135 | EuGoodsStatisticsNo |
| 137 | AssociateInformationGroup1 |
| 138 | AssociateInformationGroup2 |
| 139 | AssociateInformationGroup3 |
| 140 | AssociateInformationGroup4 |
| 141 | AssociateInformationGroup5 |
| 142 | AssociateInformationGroup6 |
| 143 | AssociateInformationGroup7 |
| 144 | AssociateInformationGroup8 |
| 145 | ProductCategory |
| 146 | CustomerPriceGroup3 |
| 147 | ProxyType |
| 148 | RoleType |
| 149 | MessageType |
| 150 | ExternalConfigurationGrouping1 |
| 151 | ExternalConfigurationGrouping2 |
| 152 | ExternalConfigurationGrouping3 |
| 153 | ExternalConfigurationGrouping4 |
| 154 | InterestRateGroup |
| 155 | SmsProvider |
| 156 | FreeInformationType1 |
| 157 | FreeInformationGrouping1 |
| 158 | FreeInformationGrouping2 |
| 159 | FreeInformationGrouping3 |
| 160 | FreeInformationGrouping4 |
| 161 | ShipmentGrouping1 |
| 162 | ShipmentGrouping2 |
| 163 | VoucherGroup1 |
| 164 | VoucherGroup2 |
| 165 | VoucherTypeText |
| 166 | AlternativeProductGrouping1 |
| 167 | AlternativeProductGrouping2 |
| 168 | StructureGrouping1 |
| 169 | StructureGrouping2 |
| 170 | StructureGrouping3 |
| 171 | StructureGrouping4 |
| 172 | StructureGrouping5 |
| 173 | StructureGrouping6 |
| 174 | StructureGrouping7 |
| 175 | StructureGrouping8 |
| 176 | StructureGrouping9 |
| 177 | StructureGrouping10 |
| 178 | StructureGrouping11 |
| 179 | StructureGrouping12 |
| 180 | FreeInformationCategory |
| 181 | ExternalExportGrouping |
| 182 | TimeScheduleBalanceGroup |
| 183 | TaxTerm |
| 184 | BankFormat |
| 185 | AppointmentDescription |
| 186 | RemittanceCodeForRemittanceAgreements |
| 187 | RegistrationTypeForPaymentAgreements |
| 188 | CommentCodeForPaymentAgreements |
| 189 | FreeInformation1Type2 |
| 190 | FreeInformation1Type3 |
| 191 | FreeInformation2Type2 |
| 192 | FreeInformation2Type3 |
| 193 | FreeInformation3Type2 |
| 194 | FreeInformation3Type3 |
| 195 | FreeInformationGrouping5 |
| 196 | FreeInformationGrouping6 |
| 197 | FreeInformationGrouping7 |
| 198 | FreeInformationGrouping8 |
| 199 | FreeInformationGrouping9 |
| 200 | FreeInformationGrouping10 |
| 201 | FreeInformationGrouping11 |
| 202 | FreeInformationGrouping12 |
| 203 | EftFormType |
| 204 | DeliveryAlternativeGrouping1 |
| 205 | DeliveryAlternativeGrouping2 |
| 206 | GiroType |
| 207 | OssTaxTerm |
| 208 | EmailTemplateGroup |
| 211 | ExemptReason |
| 212 | InvoiceNote |

## Joining values from the text table

The values from the `Text` table are usually needed when reading records from other tables. An example was previously given: reading the payment method and the delivery method of an order.
A direct joining mechanism is not available in the API (such as a `joinup_` \ `joindown_` relation). However, it is possible to read them in a single query with the help of the [@export directive](../../apireference/features/directives.md#the-export-directive).

The following example shows how to read the payment and delivery method of a particular order:

```graphql { title = "Query" }
query read_texts($cid : Int!,
                 $orderNo : Int,
                 $dm : Long = 0,
                 $pm : Long  = 0)
{
  useCompany(no : $cid)
  {
    order(filter :{orderNo :{_eq : $orderNo}})
    {
      items
      {
        orderNo
        deliveryMethod @export(as :"dm")
        paymentMethod @export(as : "pm")
      }
    }

    deliveryMethodName : text(filter: {
      languageNo :{_eq : 47} # Norwegian
      textType : {_eq : 5}   # delivery method
      textNo : {_eq : $dm}
    })
    {
      items
      {
        text
      }
    }

    paymentMethodName : text(filter: {
      languageNo :{_eq : 47} # Norwegian
      textType : {_eq : 7}   # payment method
      textNo : {_eq : $pm}
    })
    {
      items
      {
        text
      }
    }
  }
}
```

```graphql { title = "Result" }
{
  "data": {
    "useCompany": {
      "order": {
        "items": [
          {
            "orderNo": 1,
            "deliveryMethod": 4,
            "paymentMethod": 3
          }
        ]
      },
      "deliveryMethodName": {
        "items": [
          {
            "text": "Tollpost"
          }
        ]
      },
      "paymentMethodName": {
        "items": [
          {
            "text": "Visa"
          }
        ]
      }
    }
  }
}
```

What you have to do is the following:

- read the numerical value of the text type you want to retrieve (such as `paymentMethod` and `deliveryMethod` in this example)
- export this numerical value to a query variable using the `@export` directive
- make another read, this time from the `Text` table, and filter using the desired language, the appropriate text type (such as 5 for `DeliveryMethod` and 7 for `PaymentMethod`), and the text number stored in the (previously read) query variable
- you can make as many reads as you want from the `Text` table in a single query, provided you diferentiate them using [aliases](../../apireference/features/aliases.md)
</content>
</page>