> For the complete documentation index, see [llms.txt](https://hub.equipme.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hub.equipme.io/development/api-reference-pro/sales-or-billing.md).

# Sales | Billing

## List your invoices as customer or supplier

> Retrieve all invoices that are billed to your organization by your suppliers or that your organization bills to your customers regarding the 'context' parameter.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Supplier API","version":"v1"},"tags":[{"name":"Sales | Billing"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"Context":{"enum":["customer","supplier","impersonated"],"type":"string"},"InvoiceList":{"required":["items","self","total"],"type":"object","properties":{"previous":{"$ref":"#/components/schemas/ResourceLink"},"next":{"$ref":"#/components/schemas/ResourceLink"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"},"description":"The list of result items."},"total":{"type":"integer","description":"The total number of items.","format":"int32"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ResourceLink":{"required":["href"],"type":"object","properties":{"href":{"minLength":1,"type":"string","description":"The target resource URI."},"method":{"type":"string","description":"The HTTP method to use for the request.","nullable":true}},"additionalProperties":false},"Invoice":{"required":["created","id","self"],"type":"object","properties":{"supplier":{"$ref":"#/components/schemas/SupplierReference"},"customer":{"$ref":"#/components/schemas/CustomerReference"},"primarySupplier":{"$ref":"#/components/schemas/SupplierReference"},"created":{"type":"string","description":"The timestamp of the creation of the invoice.","format":"date-time"},"dueDate":{"type":"string","description":"The due date of the invoice.","format":"date-time","nullable":true},"invoiceDate":{"type":"string","description":"The date on which the invoice was issued.","format":"date-time"},"invoiceId":{"type":"string","description":"The invoice id given by the supplier.","nullable":true},"vatId":{"type":"string","description":"The Vat ID of the recipient.","nullable":true},"transactionId":{"type":"string","description":"The transaction id of the payment.","nullable":true},"chargedTo":{"type":"string","description":"The cost center for the invoice.","nullable":true},"total":{"type":"number","description":"The total cost of the invoice.","format":"double"},"totalRecurring":{"type":"number","description":"The total recurring cost of the invoice.","format":"double"},"totalOneTime":{"type":"number","description":"The total one time cost of the invoice.","format":"double"},"currencyCode":{"type":"string","description":"TMP currency code of the invoice. This will always be the default currency of the customer.","nullable":true},"items":{"$ref":"#/components/schemas/ResourceListReference"},"id":{"type":"integer","description":"The id of the invoice.","format":"int32"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"SupplierReference":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the supplier.","format":"int64"},"name":{"type":"string","description":"The name of the supplier.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"CustomerReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the customer.","format":"int32"},"name":{"minLength":1,"type":"string","description":"The name of the customer."},"customerNumber":{"type":"string","description":"Optional identifier of the customer defined by the supplier.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ResourceListReference":{"required":["self","total"],"type":"object","properties":{"total":{"type":"integer","description":"The total number of items.","format":"int32"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/billing/invoices":{"get":{"tags":["Sales | Billing"],"summary":"List your invoices as customer or supplier","description":"Retrieve all invoices that are billed to your organization by your suppliers or that your organization bills to your customers regarding the 'context' parameter.","parameters":[{"name":"customers","in":"query","description":"Filter by one or multiple specific customers (when context is supplier)","schema":{"type":"array","items":{"type":"integer","format":"int32"}}},{"name":"suppliers","in":"query","description":"Filter by one or multiple specific suppliers (when context is customer)","schema":{"type":"array","items":{"type":"integer","format":"int32"}}},{"name":"startDate","in":"query","description":"Filter invoices which have an invoice date after or at this date","schema":{"type":"string","format":"date-time"}},{"name":"endDate","in":"query","description":"Filter invoices which have an invoice date before or at this date","schema":{"type":"string","format":"date-time"}},{"name":"context","in":"query","description":"customer: retrieve items which are invoiced to you by your suppliers | supplier: retrieve items you bill your customers","schema":{"$ref":"#/components/schemas/Context"}},{"name":"search","in":"query","description":"Filter for company names and customer numbers","schema":{"type":"string"}},{"name":"sortBy","in":"query","description":"Sort the items by a given criterion","schema":{"type":"string"}},{"name":"sortOrder","in":"query","description":"Sort the items in a given order (asc|desc)","schema":{"type":"string"}},{"name":"offset","in":"query","description":"Specifies the index of the first item to return","schema":{"type":"integer","format":"int32","default":0}},{"name":"limit","in":"query","description":"Specifies the maximum number of items to return","schema":{"type":"integer","format":"int32","default":100}}],"responses":{"200":{"description":"OK: List of invoices.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/InvoiceList"}},"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceList"}},"text/json":{"schema":{"$ref":"#/components/schemas/InvoiceList"}}}},"400":{"description":"BadRequest: Query parameters are invalid.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied or resource does not exist anymore.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Retrieve a single invoice by its id

> Set the input parameter 'context' depending whether the requested invoice is billed by or to your organization.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Supplier API","version":"v1"},"tags":[{"name":"Sales | Billing"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"Context":{"enum":["customer","supplier","impersonated"],"type":"string"},"Invoice":{"required":["created","id","self"],"type":"object","properties":{"supplier":{"$ref":"#/components/schemas/SupplierReference"},"customer":{"$ref":"#/components/schemas/CustomerReference"},"primarySupplier":{"$ref":"#/components/schemas/SupplierReference"},"created":{"type":"string","description":"The timestamp of the creation of the invoice.","format":"date-time"},"dueDate":{"type":"string","description":"The due date of the invoice.","format":"date-time","nullable":true},"invoiceDate":{"type":"string","description":"The date on which the invoice was issued.","format":"date-time"},"invoiceId":{"type":"string","description":"The invoice id given by the supplier.","nullable":true},"vatId":{"type":"string","description":"The Vat ID of the recipient.","nullable":true},"transactionId":{"type":"string","description":"The transaction id of the payment.","nullable":true},"chargedTo":{"type":"string","description":"The cost center for the invoice.","nullable":true},"total":{"type":"number","description":"The total cost of the invoice.","format":"double"},"totalRecurring":{"type":"number","description":"The total recurring cost of the invoice.","format":"double"},"totalOneTime":{"type":"number","description":"The total one time cost of the invoice.","format":"double"},"currencyCode":{"type":"string","description":"TMP currency code of the invoice. This will always be the default currency of the customer.","nullable":true},"items":{"$ref":"#/components/schemas/ResourceListReference"},"id":{"type":"integer","description":"The id of the invoice.","format":"int32"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"SupplierReference":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the supplier.","format":"int64"},"name":{"type":"string","description":"The name of the supplier.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ResourceLink":{"required":["href"],"type":"object","properties":{"href":{"minLength":1,"type":"string","description":"The target resource URI."},"method":{"type":"string","description":"The HTTP method to use for the request.","nullable":true}},"additionalProperties":false},"CustomerReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the customer.","format":"int32"},"name":{"minLength":1,"type":"string","description":"The name of the customer."},"customerNumber":{"type":"string","description":"Optional identifier of the customer defined by the supplier.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ResourceListReference":{"required":["self","total"],"type":"object","properties":{"total":{"type":"integer","description":"The total number of items.","format":"int32"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/billing/invoices/{invoiceId}":{"get":{"tags":["Sales | Billing"],"summary":"Retrieve a single invoice by its id","description":"Set the input parameter 'context' depending whether the requested invoice is billed by or to your organization.","parameters":[{"name":"invoiceId","in":"path","description":"The identifier of the invoice","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"context","in":"query","description":"customer: retrieve items which are invoiced to you by your suppliers | supplier: retrieve items you bill your customers","required":true,"schema":{"$ref":"#/components/schemas/Context"}}],"responses":{"200":{"description":"OK: The requested invoice.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/Invoice"}},"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}},"text/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"400":{"description":"BadRequest: Query parameters are invalid.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied or resource does not exist anymore.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## GET /v1/billing/invoices/{invoiceId}/reports/invoice

> Generate a PDF report for a specific invoice

```json
{"openapi":"3.0.4","info":{"title":"Equipme Supplier API","version":"v1"},"tags":[{"name":"Sales | Billing"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"Context":{"enum":["customer","supplier","impersonated"],"type":"string"},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/billing/invoices/{invoiceId}/reports/invoice":{"get":{"tags":["Sales | Billing"],"summary":"Generate a PDF report for a specific invoice","parameters":[{"name":"invoiceId","in":"path","description":"The identifier of the invoice","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"language","in":"query","description":"Language of the report","schema":{"type":"string"}},{"name":"context","in":"query","description":"customer: retrieve items which are invoiced to you by your suppliers | supplier: retrieve items you bill your customers","required":true,"schema":{"$ref":"#/components/schemas/Context"}}],"responses":{"200":{"description":"OK","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad Request","content":{"application/pdf":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/pdf":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/pdf":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get filtered billing items.

> Get all billing items that pass the filters within the selected timespan. A billing item is an active\
> service instance that is charged to the customer.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Supplier API","version":"v1"},"tags":[{"name":"Sales | Billing"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"ItemType":{"enum":["fee","tax","refund","discount","credit"],"type":"string"},"ItemStatus":{"enum":["draft","pending","unbilled","invoiced","paid","overdue","canceled","refunded"],"type":"string"},"BillingCycle":{"enum":["none","daily","weekly","biweekly","monthly","annually","triennial"],"type":"string"},"Context":{"enum":["customer","supplier","impersonated"],"type":"string"},"ItemList":{"required":["items","self","total"],"type":"object","properties":{"previous":{"$ref":"#/components/schemas/ResourceLink"},"next":{"$ref":"#/components/schemas/ResourceLink"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Item"},"description":"The list of result items."},"total":{"type":"integer","description":"The total number of items.","format":"int32"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ResourceLink":{"required":["href"],"type":"object","properties":{"href":{"minLength":1,"type":"string","description":"The target resource URI."},"method":{"type":"string","description":"The HTTP method to use for the request.","nullable":true}},"additionalProperties":false},"Item":{"required":["costs","cycle","id","resource","self","startDate","status","type"],"type":"object","properties":{"supplier":{"$ref":"#/components/schemas/SupplierReference"},"customer":{"$ref":"#/components/schemas/CustomerReference"},"location":{"$ref":"#/components/schemas/LocationReference"},"employee":{"$ref":"#/components/schemas/EmployeeReference"},"group":{"$ref":"#/components/schemas/GroupReference"},"service":{"$ref":"#/components/schemas/ServiceProductReference"},"resource":{"$ref":"#/components/schemas/ServiceInstanceReference"},"invoice":{"$ref":"#/components/schemas/InvoiceReference"},"type":{"$ref":"#/components/schemas/ItemType"},"cycle":{"$ref":"#/components/schemas/BillingCycle"},"status":{"$ref":"#/components/schemas/ItemStatus"},"description":{"type":"string","description":"The technical charge description.","nullable":true},"startDate":{"type":"string","description":"The start date for the charge.","format":"date-time"},"endDate":{"type":"string","description":"The end date for the charge.","format":"date-time"},"costs":{"type":"number","description":"Costs that are billed for the resource.","format":"double"},"currencyCode":{"type":"string","description":"Gets or sets the ISO 4217 currency code associated with the transaction.","nullable":true},"id":{"type":"integer","description":"The id of the billing item.","format":"int64"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"SupplierReference":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the supplier.","format":"int64"},"name":{"type":"string","description":"The name of the supplier.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"CustomerReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the customer.","format":"int32"},"name":{"minLength":1,"type":"string","description":"The name of the customer."},"customerNumber":{"type":"string","description":"Optional identifier of the customer defined by the supplier.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"LocationReference":{"required":["id","name","self","type"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the company location.","format":"int32"},"name":{"maxLength":100,"minLength":0,"type":"string","description":"The name of the company location."},"type":{"$ref":"#/components/schemas/LocationType"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"A location can either be a company location or a work from home location."},"LocationType":{"enum":["location","warehouse","remoteWork"],"type":"string","description":"The type of location."},"EmployeeReference":{"required":["id","self","username"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the employee.","format":"int32"},"firstName":{"maxLength":100,"minLength":0,"type":"string","description":"The first/given name of the employee.","nullable":true},"lastName":{"maxLength":100,"minLength":0,"type":"string","description":"The last/family name of the employee.","nullable":true},"fullName":{"maxLength":150,"minLength":0,"type":"string","description":"Combination of last and firstname","nullable":true,"readOnly":true},"email":{"maxLength":100,"minLength":0,"type":"string","description":"The contact and login mail address.","nullable":true},"username":{"maxLength":100,"minLength":0,"pattern":"^[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*\\.[a-zA-Z]{2,}$","type":"string","description":"The username to log in to the app. The value has to be an e-mail address."},"costCenter":{"maxLength":100,"minLength":0,"type":"string","description":"The cost center of the employee.","nullable":true},"costCenterId":{"type":"integer","description":"The identifier of the cost center.","format":"int32","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"GroupReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The id to identify the group in the system.","format":"int32"},"name":{"maxLength":50,"minLength":0,"type":"string","description":"The name of the group."},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ServiceProductReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the service.","format":"int32"},"name":{"minLength":1,"type":"string","description":"The name of the service."},"category":{"type":"string","description":"The category of the service. Comes from the marketplace ProductDisplayGroup","nullable":true},"ean":{"type":"string","description":"Value to identify the service in other systems. E.g. when an other system is the source of this service. (Max. 50 characters)","nullable":true},"externalId":{"type":"string","description":"Value to identify the service in other systems. E.g. when an other system is the source of this service.","nullable":true},"supplierName":{"type":"string","description":"The supplier for this service product","nullable":true},"previewImageLink":{"type":"string","description":"Link to a small preview image for the product","nullable":true},"type":{"$ref":"#/components/schemas/ServiceProductType"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ServiceProductType":{"enum":["service","addon","foundation_service"],"type":"string","description":"Services can take on different types that define their meaning and process flows within the system."},"ServiceInstanceReference":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"The id to identify the service instance in the system.","format":"int32"},"inventoryNumber":{"maxLength":50,"minLength":0,"type":"string","description":"The inventory number of the service instance.","nullable":true},"costCenter":{"type":"string","description":"The name of the cost center to which the service instance belongs.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"InvoiceReference":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"The id of the invoice.","format":"int32"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/billing/items":{"get":{"tags":["Sales | Billing"],"summary":"Get filtered billing items.","description":"Get all billing items that pass the filters within the selected timespan. A billing item is an active\nservice instance that is charged to the customer.","parameters":[{"name":"customers","in":"query","description":"Filter by one or multiple specific customers (when context is supplier)","schema":{"type":"array","items":{"type":"integer","format":"int32"}}},{"name":"suppliers","in":"query","description":"Filter by one or multiple specific suppliers (when context is customer)","schema":{"type":"array","items":{"type":"integer","format":"int32"}}},{"name":"orders","in":"query","description":"Filter items related to one or multiple specific sales order","schema":{"type":"array","items":{"type":"integer","format":"int32"}}},{"name":"resources","in":"query","description":"Filter by one or multiple specific resources / service instances","schema":{"type":"array","items":{"type":"integer","format":"int32"}}},{"name":"invoices","in":"query","description":"Filter by one or multiple specific invoices","schema":{"type":"array","items":{"type":"integer","format":"int32"}}},{"name":"types","in":"query","description":"Filter by one or multiple types","schema":{"type":"array","items":{"$ref":"#/components/schemas/ItemType"}}},{"name":"status","in":"query","description":"Filter by one or multiple status","schema":{"type":"array","items":{"$ref":"#/components/schemas/ItemStatus"}}},{"name":"cycles","in":"query","description":"Filter by one or multiple cycles","schema":{"type":"array","items":{"$ref":"#/components/schemas/BillingCycle"}}},{"name":"startDate","in":"query","description":"Filter items that started their billing period after or at this date","schema":{"type":"string","format":"date-time"}},{"name":"endDate","in":"query","description":"Filter items that started their billing period before or at this date","schema":{"type":"string","format":"date-time"}},{"name":"context","in":"query","description":"customer: retrieve items which are invoiced to you by your suppliers | supplier: retrieve items you bill your customers","schema":{"$ref":"#/components/schemas/Context"}},{"name":"search","in":"query","description":"Filter for resource id, service name, inventory number, employee first and last name, group or location name","schema":{"type":"string"}},{"name":"sortBy","in":"query","description":"Sort the items by a given criterion","schema":{"type":"string","default":"startDate"}},{"name":"sortOrder","in":"query","description":"Sort the items in a given order (asc|desc)","schema":{"type":"string","default":"desc"}},{"name":"offset","in":"query","description":"Specifies the index of the first item to return","schema":{"type":"integer","format":"int32","default":0}},{"name":"limit","in":"query","description":"Specifies the maximum number of items to return","schema":{"type":"integer","format":"int32","default":100}}],"responses":{"200":{"description":"OK: List of billing items.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ItemList"}},"application/json":{"schema":{"$ref":"#/components/schemas/ItemList"}},"text/json":{"schema":{"$ref":"#/components/schemas/ItemList"}}}},"400":{"description":"BadRequest: Query parameters are invalid.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied or resource does not exist anymore.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Retrieve a single billing item by its id

> Set the input parameter 'context' depending whether the requested billing item is billed by or to your organization.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Supplier API","version":"v1"},"tags":[{"name":"Sales | Billing"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"Context":{"enum":["customer","supplier","impersonated"],"type":"string"},"Item":{"required":["costs","cycle","id","resource","self","startDate","status","type"],"type":"object","properties":{"supplier":{"$ref":"#/components/schemas/SupplierReference"},"customer":{"$ref":"#/components/schemas/CustomerReference"},"location":{"$ref":"#/components/schemas/LocationReference"},"employee":{"$ref":"#/components/schemas/EmployeeReference"},"group":{"$ref":"#/components/schemas/GroupReference"},"service":{"$ref":"#/components/schemas/ServiceProductReference"},"resource":{"$ref":"#/components/schemas/ServiceInstanceReference"},"invoice":{"$ref":"#/components/schemas/InvoiceReference"},"type":{"$ref":"#/components/schemas/ItemType"},"cycle":{"$ref":"#/components/schemas/BillingCycle"},"status":{"$ref":"#/components/schemas/ItemStatus"},"description":{"type":"string","description":"The technical charge description.","nullable":true},"startDate":{"type":"string","description":"The start date for the charge.","format":"date-time"},"endDate":{"type":"string","description":"The end date for the charge.","format":"date-time"},"costs":{"type":"number","description":"Costs that are billed for the resource.","format":"double"},"currencyCode":{"type":"string","description":"Gets or sets the ISO 4217 currency code associated with the transaction.","nullable":true},"id":{"type":"integer","description":"The id of the billing item.","format":"int64"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"SupplierReference":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the supplier.","format":"int64"},"name":{"type":"string","description":"The name of the supplier.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ResourceLink":{"required":["href"],"type":"object","properties":{"href":{"minLength":1,"type":"string","description":"The target resource URI."},"method":{"type":"string","description":"The HTTP method to use for the request.","nullable":true}},"additionalProperties":false},"CustomerReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the customer.","format":"int32"},"name":{"minLength":1,"type":"string","description":"The name of the customer."},"customerNumber":{"type":"string","description":"Optional identifier of the customer defined by the supplier.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"LocationReference":{"required":["id","name","self","type"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the company location.","format":"int32"},"name":{"maxLength":100,"minLength":0,"type":"string","description":"The name of the company location."},"type":{"$ref":"#/components/schemas/LocationType"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"A location can either be a company location or a work from home location."},"LocationType":{"enum":["location","warehouse","remoteWork"],"type":"string","description":"The type of location."},"EmployeeReference":{"required":["id","self","username"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the employee.","format":"int32"},"firstName":{"maxLength":100,"minLength":0,"type":"string","description":"The first/given name of the employee.","nullable":true},"lastName":{"maxLength":100,"minLength":0,"type":"string","description":"The last/family name of the employee.","nullable":true},"fullName":{"maxLength":150,"minLength":0,"type":"string","description":"Combination of last and firstname","nullable":true,"readOnly":true},"email":{"maxLength":100,"minLength":0,"type":"string","description":"The contact and login mail address.","nullable":true},"username":{"maxLength":100,"minLength":0,"pattern":"^[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*\\.[a-zA-Z]{2,}$","type":"string","description":"The username to log in to the app. The value has to be an e-mail address."},"costCenter":{"maxLength":100,"minLength":0,"type":"string","description":"The cost center of the employee.","nullable":true},"costCenterId":{"type":"integer","description":"The identifier of the cost center.","format":"int32","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"GroupReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The id to identify the group in the system.","format":"int32"},"name":{"maxLength":50,"minLength":0,"type":"string","description":"The name of the group."},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ServiceProductReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the service.","format":"int32"},"name":{"minLength":1,"type":"string","description":"The name of the service."},"category":{"type":"string","description":"The category of the service. Comes from the marketplace ProductDisplayGroup","nullable":true},"ean":{"type":"string","description":"Value to identify the service in other systems. E.g. when an other system is the source of this service. (Max. 50 characters)","nullable":true},"externalId":{"type":"string","description":"Value to identify the service in other systems. E.g. when an other system is the source of this service.","nullable":true},"supplierName":{"type":"string","description":"The supplier for this service product","nullable":true},"previewImageLink":{"type":"string","description":"Link to a small preview image for the product","nullable":true},"type":{"$ref":"#/components/schemas/ServiceProductType"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ServiceProductType":{"enum":["service","addon","foundation_service"],"type":"string","description":"Services can take on different types that define their meaning and process flows within the system."},"ServiceInstanceReference":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"The id to identify the service instance in the system.","format":"int32"},"inventoryNumber":{"maxLength":50,"minLength":0,"type":"string","description":"The inventory number of the service instance.","nullable":true},"costCenter":{"type":"string","description":"The name of the cost center to which the service instance belongs.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"InvoiceReference":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"The id of the invoice.","format":"int32"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ItemType":{"enum":["fee","tax","refund","discount","credit"],"type":"string"},"BillingCycle":{"enum":["none","daily","weekly","biweekly","monthly","annually","triennial"],"type":"string"},"ItemStatus":{"enum":["draft","pending","unbilled","invoiced","paid","overdue","canceled","refunded"],"type":"string"},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/billing/items/{itemId}":{"get":{"tags":["Sales | Billing"],"summary":"Retrieve a single billing item by its id","description":"Set the input parameter 'context' depending whether the requested billing item is billed by or to your organization.","parameters":[{"name":"itemId","in":"path","description":"The identifier of the billing item","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"context","in":"query","description":"customer: retrieve items which are invoiced to you by your suppliers | supplier: retrieve items you bill your customers","required":true,"schema":{"$ref":"#/components/schemas/Context"}}],"responses":{"200":{"description":"OK: The requested invoice.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/Item"}},"application/json":{"schema":{"$ref":"#/components/schemas/Item"}},"text/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"400":{"description":"BadRequest: Query parameters are invalid.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied or resource does not exist anymore.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hub.equipme.io/development/api-reference-pro/sales-or-billing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.