openapi: 3.0.0
info:
title: Xentral Account ReturnOrder API
version: v0.1
description: Xentral is an ERP platform.
contact:
name: Xentral
url: https://xentral.com
email: api@xentral.com
servers:
- url: https://{xentralId}.xentral.biz
description: Your Xentral Instance
variables:
xentralId:
default: xentral
- url: https://{domain}
description: Xentral at a custom domain
variables:
domain:
default: xentral.com
security:
- BearerAuth: []
tags:
- name: ReturnOrder
description: ReturnOrder
paths:
/api/v3/returnOrders:
get:
tags:
- ReturnOrder
summary: List return orders V3
description: 'This endpoint requires the following scopes: `return:read`.
Paginated list of return orders.'
operationId: GET::api-v3-returnorders
parameters:
- name: filter
in: query
description: "The filter parameter is used to filter the results of the given endpoint. \n\n\n**Supported filter operators by key:** \n\n`id`: *equals*, *notEquals*, *in*, *notIn* \n\n`documentNumber`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentDate`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals* \n\n`writeProtection`: *equals*, *notEquals* \n\n`address.id`: *equals*, *notEquals*, *in*, *notIn* \n\n`project.id`: *equals*, *notEquals*, *in*, *notIn* \n\n`tags`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`tags.id`: *equals*, *notEquals*, *in*, *notIn* \n\n`language`: *equals*, *notEquals*, *in*, *notIn* \n\n`bodyIntroduction`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`bodyOutroduction`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`project.abbreviation`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`internalDesignation`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`vatId`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`deliveryTerms`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`internalComment`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`isDocumentSent`: *equals*, *notEquals* \n\n`editor.id`: *equals*, *notEquals*, *in*, *notIn* \n\n`createdAt`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals*, *isNull*, *isNotNull* \n\n`updatedAt`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals*, *isNull*, *isNotNull* \n\n`documentAddress.name`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.title`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.contactPerson`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.department`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.subDepartment`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.addressSupplement`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.street`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.zipCode`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.city`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.state`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.country`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.gln`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.email`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.phone`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.fax`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`status`: *equals*, *notEquals*, *in*, *notIn* \n\n`sales.id`: *equals*, *notEquals*, *in*, *notIn* \n\n`customerOrderNumber`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`preferredWarehouse.id`: *equals*, *notEquals*, *in*, *notIn* \n\n`shippingMethod.id`: *equals*, *notEquals*, *in*, *notIn* \n\n`salesOrder.id`: *equals*, *notEquals*, *in*, *notIn* \n\n`invoice.id`: *equals*, *notEquals*, *in*, *notIn* \n\n`creditNote.id`: *equals*, *notEquals*, *in*, *notIn* \n\n`customerNumber`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`useAlternativeDocumentTitle`: *equals*, *notEquals* \n\n`isReturnOrderToSupplier`: *equals*, *notEquals* \n\n`progress`: *equals*, *notEquals*, *in*, *notIn*"
required: false
style: deepObject
schema:
type: array
items:
properties:
key:
type: string
enum:
- id
- documentNumber
- documentDate
- writeProtection
- address.id
- project.id
- tags
- tags.id
- language
- bodyIntroduction
- bodyOutroduction
- project.abbreviation
- internalDesignation
- vatId
- deliveryTerms
- internalComment
- isDocumentSent
- editor.id
- createdAt
- updatedAt
- documentAddress.name
- documentAddress.title
- documentAddress.contactPerson
- documentAddress.department
- documentAddress.subDepartment
- documentAddress.addressSupplement
- documentAddress.street
- documentAddress.zipCode
- documentAddress.city
- documentAddress.state
- documentAddress.country
- documentAddress.gln
- documentAddress.email
- documentAddress.phone
- documentAddress.fax
- status
- sales.id
- customerOrderNumber
- preferredWarehouse.id
- shippingMethod.id
- salesOrder.id
- invoice.id
- creditNote.id
- customerNumber
- useAlternativeDocumentTitle
- isReturnOrderToSupplier
- progress
op:
description: operator
type: string
enum:
- equals
- notEquals
- in
- notIn
- contains
- notContains
- startsWith
- endsWith
- lessThan
- lessThanOrEquals
- greaterThan
- greaterThanOrEquals
- isNull
- isNotNull
value:
description: The property value.
oneOf:
- title: String
type: string
- title: Array
type: array
items:
type: string
type: object
additionalProperties: false
- name: sort
in: query
description: Sort via id, -id, documentNumber, -documentNumber, documentDate, -documentDate, customerNumber, -customerNumber, documentAddress.country, -documentAddress.country, project.id, -project.id, createdAt, -createdAt, updatedAt and -updatedAt. Default sort is id
required: false
style: form
explode: false
schema:
type: array
items:
enum:
- id
- -id
- documentNumber
- -documentNumber
- documentDate
- -documentDate
- customerNumber
- -customerNumber
- documentAddress.country
- -documentAddress.country
- project.id
- -project.id
- createdAt
- -createdAt
- updatedAt
- -updatedAt
- name: search
in: query
description: Full-text-style search across predefined columns.
required: false
schema:
type: string
- name: include
in: query
required: false
explode: false
schema:
type: array
items:
type: string
enum:
- lineItems
- project
- address
- lineItems.product
- tags
- activity
- customFields
- lineItems.customFields
- name: x-pagination
in: header
description: 'Controls the pagination format. Available types: simple, table, cursor. Defaults to ''simple'' if not specified.'
required: false
schema:
type: string
enum:
- simple
- table
- cursor
example: simple
- name: perPage
in: query
description: 'Number of items per page. Default: 15, Max: 1000'
required: false
schema:
type: integer
example: 15
- name: page
in: query
description: Page number. Only used with simple and table pagination.
required: false
schema:
type: integer
example: 1
- name: cursor
in: query
description: The cursor to use for the paginated call. Only used with cursor pagination. Not compatible with page parameter
required: false
schema:
type: string
example: eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0
responses:
'200':
description: Paginated list of return orders.
content:
application/json:
schema:
anyOf:
- title: 'Paginated Response: simple'
properties:
data:
type: array
items:
type: object
allOf:
- properties:
id:
description: ID of the document
type: string
example: '1'
documentNumber:
description: Document number. For drafts, this will be null.
type:
- string
- 'null'
example: I-12343
documentDate:
description: Main date of the document.
type:
- string
- 'null'
format: date
example: '2023-10-01'
writeProtection:
description: Indicates if the document is write protected.
type: boolean
example: false
customerNumber:
description: Customer number of the document.
type:
- string
- 'null'
example: CUST-54321
address:
description: Address entity of the document. By default, only the ID is returned. To get the full Address object, use the `include` parameter.
anyOf:
- required:
- id
- createdAt
- updatedAt
properties:
id:
type: string
example: '42'
isDeleted:
description: Flagged if the entry was deleted.
type: boolean
example: false
createdAt:
description: Creation timestamp
type: string
format: date-time
example: '2025-03-15T09:27:00+01:00'
updatedAt:
description: Last update timestamp
type: string
format: date-time
example: '2025-10-20T14:45:12+01:00'
type: object
additionalProperties: false
- properties:
id:
type: string
type: object
- type: 'null'
project:
description: Project entity of the document. By default, only the ID is returned. To get the full Project object, use the `include` parameter.
anyOf:
- required:
- id
- name
- abbreviation
properties:
id:
type: string
example: '54'
name:
type: string
example: Standard Project
abbreviation:
type: string
example: STANDARD
type: object
additionalProperties: false
- properties:
id:
type: string
type: object
- type: 'null'
tags:
description: Tags assigned to the document. This property is only returned if the `tags` include is used.
type: array
items:
properties:
id:
description: ID of the tag
type: string
example: '4'
title:
description: Title of the tag
type: string
example: important
type: object
documentAddress:
description: The recipients postal address of the document. This is is usually the postal address of the document's address entitiy, (e.g. customer), or is populated based on the preceding document. As this address is persisted on the document level, it can however be modified independently, and does not reflect changes that occurred since the document was created.
required:
- name
properties:
name:
description: 'Represents an address consisting of a physical address and contact information.
It is used in various documents, such as invoices, delivery notes, etc.'
type: string
example: John
type:
type:
- string
- 'null'
enum:
- mrs
- mr
- company
- other
example: mr
title:
type:
- string
- 'null'
example: Ms.
contactPerson:
type:
- string
- 'null'
example: Laura Schneider
department:
type:
- string
- 'null'
example: Research & Development
subDepartment:
type:
- string
- 'null'
example: AI Lab
addressSupplement:
type:
- string
- 'null'
example: Gebäude B, 4. Etage
street:
type:
- string
- 'null'
example: Fuggerstraße 11
zipCode:
type:
- string
- 'null'
example: '86150'
city:
type:
- string
- 'null'
example: Augsburg
state:
type:
- string
- 'null'
example: BY
country:
type:
- string
- 'null'
example: DE
salutation:
type:
- string
- 'null'
example: Sehr geehrte Damen und Herren
gln:
type:
- string
- 'null'
example: '1234567890123'
email:
type:
- string
- 'null'
example: laura.schneider@xentral.com
phone:
type:
- string
- 'null'
example: +1-234-567-8900
fax:
type:
- string
- 'null'
example: +1-234-567-8901
mobile:
type:
- string
- 'null'
example: +1-234-567-8902
type: object
example:
name: John
type: mr
title: Ms.
contactPerson: Laura Schneider
department: Research & Development
subDepartment: CAI Lab
addressSupplement: Gebäude B, 4. Etage
street: Fuggerstraße 11
zipCode: '86150'
city: Augsburg
state: BY
country: DE
salutation: Sehr geehrte Damen und Herren
gln: '1234567890123'
email: alice@example.com
phone: +1-234-567-8900
fax: +1-234-567-8901
mobile: +1-234-567-8902
additionalProperties: false
internalDesignation:
description: Internal designation, might be displayed in the letterhead.
type:
- string
- 'null'
example: FB-3860-L
isDocumentSent:
description: Indicates if the document has been sent to the recipient.
type: boolean
example: false
language:
description: ISO 639-1 Language of the document.
type: string
example: de
bodyIntroduction:
description: Text displayed on the document before the line items.
type:
- string
- 'null'
example: Dear customer, we are pleased to send you the following invoice.
bodyOutroduction:
description: Text displayed on the document after the line items.
type:
- string
- 'null'
example: Thank you for your business.
vatId:
description: VAT ID of the document.
type:
- string
- 'null'
example: DE123456789
deliveryTerms:
description: Delivery terms of the document.
type:
- string
- 'null'
example: DDP
internalComment:
description: Internal comment, does not show up on the document. Intended to be used for company-internal notes.
type:
- string
- 'null'
example: This is an internal comment.
editor:
properties:
id:
description: ID of the user who is responsible for the document.
type: string
example: '4'
type:
- object
- 'null'
printSettings:
properties:
withoutLetterhead:
description: For PDFs or physical documents, hide the letterhead
type: boolean
example: false
withoutProductText:
description: For PDFs or physical documents, hide the product text
type: boolean
example: false
type: object
activity:
description: Activity log entries associated with the document. To get activity object, use the `include` parameter.
type: array
items:
required:
- message
- causer
- causedAt
properties:
message:
type: string
example: Invoice released
causer:
type:
- string
- 'null'
example: John Doe
causedAt:
type: string
format: date-time
example: '2023-01-01T00:00:00Z'
type: object
additionalProperties: false
customFields:
description: Custom fields with their values and metadata
type: array
items:
properties:
key:
type: string
example: customField1
value:
type:
- string
- 'null'
example: prospect
label:
type: string
example: lifecycle
type: object
example:
- key: customer_category
value: Premium
label: Customer Category
- key: priority_level
value: High
label: Priority Level
updatedAt:
type: string
format: date-time
example: '2023-10-01T12:00:00Z'
createdAt:
type: string
format: date-time
example: '2023-10-01T12:00:00Z'
type: object
- properties:
salesOrder:
description: Sales order reference.
properties:
id:
description: ID of the sales order
type: string
example: '13'
type:
- object
- 'null'
type: object
- properties:
invoice:
description: invoice reference.
properties:
id:
description: ID of the invoice
type: string
example: '13'
type:
- object
- 'null'
type: object
- properties:
preferredWarehouse:
description: Preferred warehouse for the document.
properties:
id:
description: ID of the preferred warehouse
type: string
example: '15'
type:
- object
- 'null'
type: object
- properties:
sales:
description: Sales person responsible for the document.
properties:
id:
type: string
example: '1'
type:
- object
- 'null'
type: object
- properties:
status:
description: Status of the document.
type: string
enum:
- draft
- released
- completed
- cancelled
example: released
customerOrderNumber:
description: Customer order number of the return order, e.g. the customer's order number.
type:
- string
- 'null'
example: CUST-54321
creditNote:
description: Credit note connected to the return order.
properties:
id:
type: string
example: '13'
type:
- object
- 'null'
deliveryNote:
description: Delivery note connected to the return order.
properties:
id:
type: string
example: '16'
type:
- object
- 'null'
replacementSalesOrder:
description: Replacement sales order connected to the return order.
properties:
id:
type: string
example: '20'
type:
- object
- 'null'
progress:
description: Progress of the return order.
type: string
enum:
- announced
- received
- checked
# --- truncated at 32 KB (509 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/xentral/refs/heads/main/openapi/xentral-returnorder-api-openapi.yml