Orders

Contact information related to different aspects in the lifecycle of an Order.

currency

string

The currency for this Order.

Default: NOK

externalReference

string

External reference for Orders

Example: 3N7URR0X

expireAt

string · date-time

Any changes not confirmed before this point in time will be discarded. Default is 20 minutes from the last operation. Cannot be in the past, or further into the future than six months.

Example: 2020-05-13T07:19:30.389Z

Create an empty Order, and return the Order object › Responses

A purchase Order for one or more Travellers

id

string · required

ID of Order.

Example: 3N7URR0X

version

integer · int32 · required

The system increments an Order’s version number whenever some change occurs that causes the Order’s status to go from CONFIRMED to DRAFT. The user has to perform an action that causes the status to go from DRAFT to CONFIRMED (such as paying for the Order) before the time given in expireAt. If the Order is not confirmed within this time, the system will scrap all changes (including the incremented version) and return the Order to its last confirmed version.

Example: 2

Default: 1

status

WorkflowStatus · enum · required

Status of this Order or OrderLine. Every Order starts out with the status DRAFT, and can only be changed to CONFIRMED when it is balanced - when balance is '0.00'. All OrderLines that are have the status DRAFT at that point in time can also be changed to CONFIRMED.

Enum values:

DRAFT

CONFIRMED

Example: CONFIRMED

Default: DRAFT

totalAmount

string · required

The total amount due for this Order.

Default: 0.00

balance

string · required

The balance amount for this Order.

Default: 0.00

totalTaxAmount

string · required

The total tax amount for this Order.

Default: 0.00

currency

string · required

The currency for this Order.

Default: NOK

OrderLine[] · required

OrderLines in the given Order.

Default: []

PaymentRef[] · required

Payment references used on this Order.

Default: []

PurchasedReservation[] · required

Seating Reservations connected to this Order.

Default: []

Traveller[] · required

Unique Travellers in this Order.

Default: []

organisationId

integer · int64 · required

ID of the organisation which created/sold this Order.

Example: 1

createdAt

string · date-time · required

Timestamp for when Order was created.

Example: 2020-05-13T07:19:30.389Z

Fee[] · required

Fees contained in the Order.

Default: []

failed

boolean · required

Indicates that the order version has failed and needs to be credited.

Default: false

lastConfirmedAt

string · date-time

Timestamp for when Order was last confirmed.

Example: 2020-05-13T07:19:30.389Z

pos

string

Point-of-sale reference of request used when Order was created

Example: POS-123

distributionChannelId

string

Distribution channel ID of request used when Order was created

Example: ENT:DistributionChannel:Sor

Contact information related to different aspects in the lifecycle of an Order.

externalReference

string

External reference for Orders

Example: 3N7URR0X

expireAt

string · date-time

Any changes not confirmed before this point in time will be discarded. Default is 20 minutes from the last operation. Cannot be in the past, or further into the future than six months.

Example: 2020-05-13T07:19:30.389Z

Holder for fields used to explain why an Order has been issued. Used for zero tickets.

POST/v1/orders

curl https://api.staging.entur.io/sales/v1/orders \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Entur-Distribution-Channel: <string>' \
  --header 'Entur-Pos: <string>' \
  --data '{
  "contactInfo": {
    "createdBy": {
      "id": "12345678"
    },
    "contact": {
      "id": "12345678"
    }
  },
  "externalReference": "some-external-ref-123",
  "expireAt": "2030-05-13T07:19:30.389Z"
}'

Example Request Body

{
  "contactInfo": {
    "createdBy": {
      "id": "12345678"
    },
    "contact": {
      "id": "12345678"
    }
  },
  "externalReference": "some-external-ref-123",
  "expireAt": "2030-05-13T07:19:30.389Z"
}

json

Example Responses

{
  "contactInfo": {
    "createdBy": {
      "id": "12345678"
    },
    "contact": {
      "id": "12345678"
    }
  },
  "externalReference": "some-external-ref-123",
  "expireAt": "2030-05-13T07:19:30.389Z",
  "specialOrderCause": {
    "causeCode": "DELAY",
    "description": "Train was delayed."
  }
}

json

application/json

Get Order with ID in latest version

GET

https://api.staging.entur.io/sales

/v1/orders/{orderId}

Get the latest versioned Order. Earlier versions with status CONFIRMED can be retrieved by specifying version=<desired version, minimum 1>.

Get Order with ID in latest version › path Parameters

orderId

string · required · style: simple

Order ID

Get Order with ID in latest version › query Parameters

version

integer · int32 · min: 1 · style: form · explode: true

Optional version query

Get Order with ID in latest version › Headers

ET-Client-Name

string · style: simple

X-Correlation-Id

string · style: simple

Correlation id

Get Order with ID in latest version › Responses

A purchase Order for one or more Travellers

id

string · required

ID of Order.

Example: 3N7URR0X

version

integer · int32 · required

Example: 2

Default: 1

status

WorkflowStatus · enum · required

Enum values:

DRAFT

CONFIRMED

Example: CONFIRMED

Default: DRAFT

totalAmount

string · required

The total amount due for this Order.

Default: 0.00

balance

string · required

The balance amount for this Order.

Default: 0.00

totalTaxAmount

string · required

The total tax amount for this Order.

Default: 0.00

currency

string · required

The currency for this Order.

Default: NOK

OrderLine[] · required

OrderLines in the given Order.

Default: []

PaymentRef[] · required

Payment references used on this Order.

Default: []

PurchasedReservation[] · required

Seating Reservations connected to this Order.

Default: []

Traveller[] · required

Unique Travellers in this Order.

Default: []

organisationId

integer · int64 · required

ID of the organisation which created/sold this Order.

Example: 1

createdAt

string · date-time · required

Timestamp for when Order was created.

Example: 2020-05-13T07:19:30.389Z

Fee[] · required

Fees contained in the Order.

Default: []

failed

boolean · required

Indicates that the order version has failed and needs to be credited.

Default: false

lastConfirmedAt

string · date-time

Timestamp for when Order was last confirmed.

Example: 2020-05-13T07:19:30.389Z

pos

string

Point-of-sale reference of request used when Order was created

Example: POS-123

distributionChannelId

string

Distribution channel ID of request used when Order was created

Example: ENT:DistributionChannel:Sor

Contact information related to different aspects in the lifecycle of an Order.

externalReference

string

External reference for Orders

Example: 3N7URR0X

expireAt

string · date-time

Any changes not confirmed before this point in time will be discarded. Default is 20 minutes from the last operation. Cannot be in the past, or further into the future than six months.

Example: 2020-05-13T07:19:30.389Z

Holder for fields used to explain why an Order has been issued. Used for zero tickets.

Update an Order.

PUT

https://api.staging.entur.io/sales

/v1/orders/{orderId}

Update one or multiple values on an Order.

Update an Order. › path Parameters

orderId

string · required · style: simple

Order ID

Update an Order. › Headers

Entur-Distribution-Channel

string · required · style: simple

A header containing the distribution channel ID.

Entur-Pos

string · required · style: simple

Point-of-sale identifier.

ET-Client-Name

string · style: simple

X-Correlation-Id

string · style: simple

Correlation id

Update an Order. › Request Body

A purchase Order for one or more Travellers

OrderRequest

Contact information related to different aspects in the lifecycle of an Order.

externalReference

string

External reference for Orders

Example: 3N7URR0X

expireAt

string · date-time

Any changes not confirmed before this point in time will be discarded. Default is 20 minutes from the last operation. Cannot be in the past, or further into the future than six months.

Example: 2020-05-13T07:19:30.389Z

Holder for fields used to explain why an Order has been issued. Used for zero tickets.

Update an Order. › Responses

A purchase Order for one or more Travellers

id

string · required

ID of Order.

Example: 3N7URR0X

version

integer · int32 · required

Example: 2

Default: 1

status

WorkflowStatus · enum · required

Enum values:

DRAFT

CONFIRMED

Example: CONFIRMED

Default: DRAFT

totalAmount

string · required

The total amount due for this Order.

Default: 0.00

balance

string · required

The balance amount for this Order.

Default: 0.00

totalTaxAmount

string · required

The total tax amount for this Order.

Default: 0.00

currency

string · required

The currency for this Order.

Default: NOK

OrderLine[] · required

OrderLines in the given Order.

Default: []

PaymentRef[] · required

Payment references used on this Order.

Default: []

PurchasedReservation[] · required

Seating Reservations connected to this Order.

Default: []

Traveller[] · required

Unique Travellers in this Order.

Default: []

organisationId

integer · int64 · required

ID of the organisation which created/sold this Order.

Example: 1

createdAt

string · date-time · required

Timestamp for when Order was created.

Example: 2020-05-13T07:19:30.389Z

Fee[] · required

Fees contained in the Order.

Default: []

failed

boolean · required

Indicates that the order version has failed and needs to be credited.

Default: false

lastConfirmedAt

string · date-time

Timestamp for when Order was last confirmed.

Example: 2020-05-13T07:19:30.389Z

pos

string

Point-of-sale reference of request used when Order was created

Example: POS-123

distributionChannelId

string

Distribution channel ID of request used when Order was created

Example: ENT:DistributionChannel:Sor

Contact information related to different aspects in the lifecycle of an Order.

externalReference

string

External reference for Orders

Example: 3N7URR0X

expireAt

string · date-time

Any changes not confirmed before this point in time will be discarded. Default is 20 minutes from the last operation. Cannot be in the past, or further into the future than six months.

Example: 2020-05-13T07:19:30.389Z

Holder for fields used to explain why an Order has been issued. Used for zero tickets.

PUT/v1/orders/{orderId}

curl https://api.staging.entur.io/sales/v1/orders/:orderId \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Entur-Distribution-Channel: <string>' \
  --header 'Entur-Pos: <string>' \
  --data '{
  "contactInfo": {
    "createdBy": {
      "id": "12345678"
    },
    "contact": {
      "id": "12345678"
    }
  },
  "externalReference": "some-external-ref-123",
  "expireAt": "2030-05-13T07:19:30.389Z",
  "specialOrderCause": {
    "causeCode": "DELAY",
    "description": "Train was delayed."
  }
}'

Example Request Body

{
  "contactInfo": {
    "createdBy": {
      "id": "12345678"
    },
    "contact": {
      "id": "12345678"
    }
  },
  "externalReference": "some-external-ref-123",
  "expireAt": "2030-05-13T07:19:30.389Z",
  "specialOrderCause": {
    "causeCode": "DELAY",
    "description": "Train was delayed."
  }
}

json

Example Responses

{
  "contactInfo": {
    "createdBy": {
      "id": "12345678"
    },
    "contact": {
      "id": "12345678"
    }
  },
  "externalReference": "some-external-ref-123",
  "expireAt": "2030-05-13T07:19:30.389Z",
  "specialOrderCause": {
    "causeCode": "DELAY",
    "description": "Train was delayed."
  }
}

json

application/json

Unlock Order

POST

https://api.staging.entur.io/sales

/v1/orders/{orderId}/unlock

Unlock order if it is locked.

Unlock Order › path Parameters

orderId

string · required · style: simple

Order ID

Unlock Order › Headers

Entur-Distribution-Channel

string · required · style: simple

A header containing the distribution channel ID.

Entur-Pos

string · required · style: simple

Point-of-sale identifier.

ET-Client-Name

string · style: simple

X-Correlation-Id

string · style: simple

Correlation id

Unlock Order › Responses

A purchase Order for one or more Travellers

id

string · required

ID of Order.

Example: 3N7URR0X

version

integer · int32 · required

Example: 2

Default: 1

status

WorkflowStatus · enum · required

Enum values:

DRAFT

CONFIRMED

Example: CONFIRMED

Default: DRAFT

totalAmount

string · required

The total amount due for this Order.

Default: 0.00

balance

string · required

The balance amount for this Order.

Default: 0.00

totalTaxAmount

string · required

The total tax amount for this Order.

Default: 0.00

currency

string · required

The currency for this Order.

Default: NOK

OrderLine[] · required

OrderLines in the given Order.

Default: []

PaymentRef[] · required

Payment references used on this Order.

Default: []

PurchasedReservation[] · required

Seating Reservations connected to this Order.

Default: []

Traveller[] · required

Unique Travellers in this Order.

Default: []

organisationId

integer · int64 · required

ID of the organisation which created/sold this Order.

Example: 1

createdAt

string · date-time · required

Timestamp for when Order was created.

Example: 2020-05-13T07:19:30.389Z

Fee[] · required

Fees contained in the Order.

Default: []

failed

boolean · required

Indicates that the order version has failed and needs to be credited.

Default: false

lastConfirmedAt

string · date-time

Timestamp for when Order was last confirmed.

Example: 2020-05-13T07:19:30.389Z

pos

string

Point-of-sale reference of request used when Order was created

Example: POS-123

distributionChannelId

string

Distribution channel ID of request used when Order was created

Example: ENT:DistributionChannel:Sor

Contact information related to different aspects in the lifecycle of an Order.

externalReference

string

External reference for Orders

Example: 3N7URR0X

expireAt

string · date-time

Any changes not confirmed before this point in time will be discarded. Default is 20 minutes from the last operation. Cannot be in the past, or further into the future than six months.

Example: 2020-05-13T07:19:30.389Z

Holder for fields used to explain why an Order has been issued. Used for zero tickets.

Fail Order

POST

https://api.staging.entur.io/sales

/v1/orders/{orderId}/fail

Fail the order and order lines that have externalConfirmation=PENDING. An OrderFailed event is emitted and the order transitions to CONFIRMED with failed=true. Returns 200 with the current order state, including if the order is already confirmed or failed.

Fail Order › path Parameters

orderId

string · required · style: simple

Order ID

Fail Order › Headers

Entur-Distribution-Channel

string · required · style: simple

A header containing the distribution channel ID.

Entur-Pos

string · required · style: simple

Point-of-sale identifier.

ET-Client-Name

string · style: simple

X-Correlation-Id

string · style: simple

Correlation id

Fail Order › Request Body

FailOrderRequest

orderLineIds

string[] · required

IDs of order lines that failed external confirmation. Must be order lines with externalConfirmation=PENDING.

Fail Order › Responses

A purchase Order for one or more Travellers

id

string · required

ID of Order.

Example: 3N7URR0X

version

integer · int32 · required

Example: 2

Default: 1

status

WorkflowStatus · enum · required

Enum values:

DRAFT

CONFIRMED

Example: CONFIRMED

Default: DRAFT

totalAmount

string · required

The total amount due for this Order.

Default: 0.00

balance

string · required

The balance amount for this Order.

Default: 0.00

totalTaxAmount

string · required

The total tax amount for this Order.

Default: 0.00

currency

string · required

The currency for this Order.

Default: NOK

OrderLine[] · required

OrderLines in the given Order.

Default: []

PaymentRef[] · required

Payment references used on this Order.

Default: []

PurchasedReservation[] · required

Seating Reservations connected to this Order.

Default: []

Traveller[] · required

Unique Travellers in this Order.

Default: []

organisationId

integer · int64 · required

ID of the organisation which created/sold this Order.

Example: 1

createdAt

string · date-time · required

Timestamp for when Order was created.

Example: 2020-05-13T07:19:30.389Z

Fee[] · required

Fees contained in the Order.

Default: []

failed

boolean · required

Indicates that the order version has failed and needs to be credited.

Default: false

lastConfirmedAt

string · date-time

Timestamp for when Order was last confirmed.

Example: 2020-05-13T07:19:30.389Z

pos

string

Point-of-sale reference of request used when Order was created

Example: POS-123

distributionChannelId

string

Distribution channel ID of request used when Order was created

Example: ENT:DistributionChannel:Sor

Contact information related to different aspects in the lifecycle of an Order.

externalReference

string

External reference for Orders

Example: 3N7URR0X

expireAt

string · date-time

Any changes not confirmed before this point in time will be discarded. Default is 20 minutes from the last operation. Cannot be in the past, or further into the future than six months.

Example: 2020-05-13T07:19:30.389Z

Holder for fields used to explain why an Order has been issued. Used for zero tickets.

POST/v1/orders/{orderId}/fail

curl https://api.staging.entur.io/sales/v1/orders/:orderId/fail \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Entur-Distribution-Channel: <string>' \
  --header 'Entur-Pos: <string>' \
  --data '{
  "orderLineIds": [
    "00000000-0000-0000-0000-000000000000"
  ]
}'

Example Request Body

{
  "orderLineIds": [
    "00000000-0000-0000-0000-000000000000"
  ]
}

json

Example Responses

{
  "contactInfo": {
    "createdBy": {
      "id": "12345678"
    },
    "contact": {
      "id": "12345678"
    }
  },
  "externalReference": "some-external-ref-123",
  "expireAt": "2030-05-13T07:19:30.389Z",
  "specialOrderCause": {
    "causeCode": "DELAY",
    "description": "Train was delayed."
  }
}

json

application/json

Confirm Order

POST

https://api.staging.entur.io/sales

/v1/orders/{orderId}/confirm

Manually confirm Orders where the balance is equal to 0.00

Confirm Order › path Parameters

orderId

string · required · style: simple

Order ID

Confirm Order › Headers

Entur-Distribution-Channel

string · required · style: simple

A header containing the distribution channel ID.

Entur-Pos

string · required · style: simple

Point-of-sale identifier.

ET-Client-Name

string · style: simple

X-Correlation-Id

string · style: simple

Correlation id

Confirm Order › Responses

A purchase Order for one or more Travellers

id

string · required

ID of Order.

Example: 3N7URR0X

version

integer · int32 · required

Example: 2

Default: 1

status

WorkflowStatus · enum · required

Enum values:

DRAFT

CONFIRMED

Example: CONFIRMED

Default: DRAFT

totalAmount

string · required

The total amount due for this Order.

Default: 0.00

balance

string · required

The balance amount for this Order.

Default: 0.00

totalTaxAmount

string · required

The total tax amount for this Order.

Default: 0.00

currency

string · required

The currency for this Order.

Default: NOK

OrderLine[] · required

OrderLines in the given Order.

Default: []

PaymentRef[] · required

Payment references used on this Order.

Default: []

PurchasedReservation[] · required

Seating Reservations connected to this Order.

Default: []

Traveller[] · required

Unique Travellers in this Order.

Default: []

organisationId

integer · int64 · required

ID of the organisation which created/sold this Order.

Example: 1

createdAt

string · date-time · required

Timestamp for when Order was created.

Example: 2020-05-13T07:19:30.389Z

Fee[] · required

Fees contained in the Order.

Default: []

failed

boolean · required

Indicates that the order version has failed and needs to be credited.

Default: false

lastConfirmedAt

string · date-time

Timestamp for when Order was last confirmed.

Example: 2020-05-13T07:19:30.389Z

pos

string

Point-of-sale reference of request used when Order was created

Example: POS-123

distributionChannelId

string

Distribution channel ID of request used when Order was created

Example: ENT:DistributionChannel:Sor

Contact information related to different aspects in the lifecycle of an Order.

externalReference

string

External reference for Orders

Example: 3N7URR0X

expireAt

string · date-time

Any changes not confirmed before this point in time will be discarded. Default is 20 minutes from the last operation. Cannot be in the past, or further into the future than six months.

Example: 2020-05-13T07:19:30.389Z

Holder for fields used to explain why an Order has been issued. Used for zero tickets.

Reset Order to the latest confirmed version, or initial state if it has never been confirmed

POST

https://api.staging.entur.io/sales

/v1/orders/{orderId}/reset

This can be used when customers spend too much time placing an Order with a seat Reservation. By using reset, the application will free up space so that the seats can be reserved by others.

Reset Order to the latest confirmed version, or initial state if it has never been confirmed › path Parameters

orderId

string · required · style: simple

Order ID

Reset Order to the latest confirmed version, or initial state if it has never been confirmed › Headers

Entur-Distribution-Channel

string · required · style: simple

A header containing the distribution channel ID.

Entur-Pos

string · required · style: simple

Point-of-sale identifier.

ET-Client-Name

string · style: simple

X-Correlation-Id

string · style: simple

Correlation id

Reset Order to the latest confirmed version, or initial state if it has never been confirmed › Responses

A purchase Order for one or more Travellers

id

string · required

ID of Order.

Example: 3N7URR0X

version

integer · int32 · required

Example: 2

Default: 1

status

WorkflowStatus · enum · required

Enum values:

DRAFT

CONFIRMED

Example: CONFIRMED

Default: DRAFT

totalAmount

string · required

The total amount due for this Order.

Default: 0.00

balance

string · required

The balance amount for this Order.

Default: 0.00

totalTaxAmount

string · required

The total tax amount for this Order.

Default: 0.00

currency

string · required

The currency for this Order.

Default: NOK

OrderLine[] · required

OrderLines in the given Order.

Default: []

PaymentRef[] · required

Payment references used on this Order.

Default: []

PurchasedReservation[] · required

Seating Reservations connected to this Order.

Default: []

Traveller[] · required

Unique Travellers in this Order.

Default: []

organisationId

integer · int64 · required

ID of the organisation which created/sold this Order.

Example: 1

createdAt

string · date-time · required

Timestamp for when Order was created.

Example: 2020-05-13T07:19:30.389Z

Fee[] · required

Fees contained in the Order.

Default: []

failed

boolean · required

Indicates that the order version has failed and needs to be credited.

Default: false

lastConfirmedAt

string · date-time

Timestamp for when Order was last confirmed.

Example: 2020-05-13T07:19:30.389Z

pos

string

Point-of-sale reference of request used when Order was created

Example: POS-123

distributionChannelId

string

Distribution channel ID of request used when Order was created

Example: ENT:DistributionChannel:Sor

Contact information related to different aspects in the lifecycle of an Order.

externalReference

string

External reference for Orders

Example: 3N7URR0X

expireAt

string · date-time

Any changes not confirmed before this point in time will be discarded. Default is 20 minutes from the last operation. Cannot be in the past, or further into the future than six months.

Example: 2020-05-13T07:19:30.389Z