Supplement product

Server

A supplement product can be purchased in addition to a preassigned fare product. Examples of supplement product types include:

Seat reservation
Bicycle
Animal
Meal
Wi-fi
Luggage
Parking

Create a new supplement product

POST

https://api.entur.io/products

/v3/supplement-products

Create a new supplement product. A new version will be created with version number 1.

Create a new supplement product › Headers

ET-Client-Name

string

Entur Client Header. It is required that all consumers identify themselves by using this header. Entur will deploy strict rate-limiting policies on API-consumers who do not identify with a header and reserves the right to block unidentified consumers. The structure of ET-Client-Name should be: <company>-<application> for companies, and <personal name>-<application> for individuals.

X-Correlation-Id

string

Correlation id

Create a new supplement product › Request Body

SupplementProductRequest

object[] · required

status

string · enum · required

Status of the supplement product. Defaults to VERSIONED.

DRAFT - Under construction and not ready for operational use.
PROPOSED - Complete but pending review and approval.
VERSIONED - Finalized and frozen; a new version must be created for further modifications. Remains authoritative for its validity period even after expiry.
DEPRECATED - Explicitly withdrawn and should not be used; indicates an active decision to retract, not a natural expiry.

Enum values:

DRAFT

PROPOSED

VERSIONED

DEPRECATED

Example: VERSIONED

vatGroup

VatGrpupType · enum · required

VAT group type. This is used to determine which VAT rate applies to a product. The VAT group type is determined by the product type and the country of sale. For example, in Norway, food products are subject to a reduced VAT rate of 15%, while other products are subject to the standard VAT rate of 25%. In this case, food products would be classified as FOOD_VAT, while other products would be classified as GENERAL_VAT.

Enum values:

EXCEPTION_FROM_VAT

GENERAL_VAT

FOOD_VAT

TRANSPORT_AND_TICKETS_VAT

Default: TRANSPORT_AND_TICKETS_VAT

object · required

startDate

string · date · required

The start date of the version.

ConditionsSummary · required

purchaseWindowRef

string · pattern: ^([A-Z]{3}):Purchase… · required

NeTEx ID of a PurchaseWindow instance (limitations/purchase-window). Available values are listed in the Parameter Catalog API.

Example: ENT:PurchaseWindow:120days

chargingMomentType

ChargingMomentType · enum · required

Charging moment type.

Note: Currently, only BEFORE_TRAVEL is supported in Entur sales platform.

Enum values:

BEFORE_TRAVEL

ON_START_OF_TRAVEL

BEFORE_END_OF_TRAVEL

BEFORE_TRAVEL_THEN_ADJUST_AT_END_OF_TRAVEL

ON_START_THEN_ADJUST_AT_END_OF_TRAVEL

ON_START_THEN_ADJUST_AT_END_OF_FARE_DAY

ON_START_THEN_ADJUST_AT_END_OF_CHARGE_PERIOD

AT_END_OF_TRAVEL

ValidityParameters[] · required

List of validity parameters. The specified parameter tells where the supplement product is valid. This can be lines, zones, stops etc.

ownerOrganisationId

integer · int64 · required

The ID of the organization that owns the supplement product. Available organizations can be retrieved from the Organization Management API (external to this specification).

supplementProductType

SupplementProductType · enum · required

The type of the supplement product. This can be used to determine which parameters are relevant for the product.

Enum values:

SEAT_RESERVATION

BICYCLE

DOG

ANIMAL

MEAL

WIFI

EXTRA_LUGGAGE

PENALTY

usageValidityPeriodRef

string · pattern: ^([A-Z]{3}):UsageVal… · required

NeTEx ID of a UsageValidityPeriod instance (limitations/usage-validity-period). Available values are listed in the Parameter Catalog API.

Example: ENT:UsageValidityPeriod:DuringTravel

entitlementRequiredRefs

string[] · minItems: 1 · required

List of NeTEx IDs of EntitlementRequired instances (limitations/entitlement-required). Available values are listed in the Parameter Catalog API.

endDate

string · date

The end date of the version (optional).

privateCode

string

Optional external system identifier. Used to generate the NeTEx ID as the last segment (e.g., privateCode '123' produces 'XXX:SupplementProduct:123'). If not provided, the NeTEx ID will be generated automatically.

Example: 123

object[]

Create a new supplement product › Responses

Supplement product created successfully

SupplementProductResponse

id

string · pattern: ^([A-Z]{3}):Suppleme… · required

The NeTEx ID of the supplement product.

Example: BNR:SupplementProduct:123

object[] · required

status

string · enum · required

Status of the supplement product.

DRAFT - Under construction and not ready for operational use.
PROPOSED - Complete but pending review and approval.
VERSIONED - Finalized and frozen; a new version must be created for further modifications. Remains authoritative for its validity period even after expiry.
DEPRECATED - Explicitly withdrawn and should not be used; indicates an active decision to retract, not a natural expiry.

Enum values:

DRAFT

PROPOSED

VERSIONED

DEPRECATED

Example: VERSIONED

vatGroup

VatGrpupType · enum · required

Enum values:

EXCEPTION_FROM_VAT

GENERAL_VAT

FOOD_VAT

TRANSPORT_AND_TICKETS_VAT

Default: TRANSPORT_AND_TICKETS_VAT

object · required

startDate

string · date · required

The start date of the version.

versionId

string · pattern: ^([A-Z]{3}):Version:… · required

The netex id reference to the object.

Example: EXA:Version:001

ConditionsSummary · required

purchaseWindowRef

string · pattern: ^([A-Z]{3}):Purchase… · required

NeTEx ID of a PurchaseWindow instance (limitations/purchase-window). Available values are listed in the Parameter Catalog API.

Example: ENT:PurchaseWindow:120days

chargingMomentType

ChargingMomentType · enum · required

Charging moment type.

Note: Currently, only BEFORE_TRAVEL is supported in Entur sales platform.

Enum values:

BEFORE_TRAVEL

ON_START_OF_TRAVEL

BEFORE_END_OF_TRAVEL

BEFORE_TRAVEL_THEN_ADJUST_AT_END_OF_TRAVEL

ON_START_THEN_ADJUST_AT_END_OF_TRAVEL

ON_START_THEN_ADJUST_AT_END_OF_FARE_DAY

ON_START_THEN_ADJUST_AT_END_OF_CHARGE_PERIOD

AT_END_OF_TRAVEL

ValidityParameters[] · required

List of validity parameters. The specified parameter tells where the supplement product is valid. This can be lines, zones, stops etc.

ownerOrganisationId

integer · int64 · required

The ID of the organization that owns the supplement product. Refer to your organization management service or documentation for how to obtain valid organization IDs.

supplementProductType

SupplementProductType · enum · required

The type of the supplement product. This can be used to determine which parameters are relevant for the product.

Enum values:

SEAT_RESERVATION

BICYCLE

DOG

ANIMAL

MEAL

WIFI

EXTRA_LUGGAGE

PENALTY

usageValidityPeriodRef

string · pattern: ^([A-Z]{3}):UsageVal… · required

NeTEx ID of a UsageValidityPeriod instance (limitations/usage-validity-period). Available values are listed in the Parameter Catalog API.

Example: ENT:UsageValidityPeriod:DuringTravel

entitlementRequiredRefs

string[] · minItems: 1 · required

List of NeTEx IDs of EntitlementRequired instances (limitations/entitlement-required). Available values are listed in the Parameter Catalog API.

endDate

string · date

The end date of the version (optional).

object

The datasource that owns this supplement product.

privateCode

string

Example: 123

object[]

versionNumber

integer · int64

Version number of the version. Only present when versionStatus is VERSIONED. Starts at 1 for a new product and is incremented by 1 for each new version.

Example: 1

POST/v3/supplement-products

curl https://api.entur.io/products/v3/supplement-products \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "names": [
    {
      "lang": "en-GB",
      "value": "Dog"
    },
    {
      "lang": "nb-NO",
      "value": "Hund"
    }
  ],
  "status": "DRAFT",
  "vatGroup": "TRANSPORT_AND_TICKETS_VAT",
  "farePrice": {
    "amount": 30,
    "currency": "NOK"
  },
  "startDate": "2025-01-01",
  "descriptions": [
    {
      "lang": "en-GB",
      "value": "Bring your dog onboard the train."
    },
    {
      "lang": "nb-NO",
      "value": "Ta med hunden din ombord på toget."
    }
  ],
  "conditionsSummary": {
    "refundable": true,
    "exchangeable": true,
    "fareStructureType": "POINT_TO_POINT_FARE"
  },
  "purchaseWindowRef": "EXA:PurchaseWindow:90days",
  "chargingMomentType": "BEFORE_TRAVEL",
  "validityParameters": [
    {
      "groupingType": "OR",
      "validityParameterRefs": [
        "EXA:FareZone:A",
        "EXA:FareZone:B"
      ],
      "validityParameterType": "ZONE"
    }
  ],
  "ownerOrganisationId": 1,
  "supplementProductType": "DOG",
  "usageValidityPeriodRef": "EXA:UsageValidityPeriod:60minutes",
  "entitlementRequiredRefs": [
    "EXA:EntitlementRequired:StandardTicket"
  ]
}'

Example Request Body

{
  "names": [
    {
      "lang": "en-GB",
      "value": "Dog"
    },
    {
      "lang": "nb-NO",
      "value": "Hund"
    }
  ],
  "status": "DRAFT",
  "vatGroup": "TRANSPORT_AND_TICKETS_VAT",
  "farePrice": {
    "amount": 30,
    "currency": "NOK"
  },
  "startDate": "2025-01-01",
  "descriptions": [
    {
      "lang": "en-GB",
      "value": "Bring your dog onboard the train."
    },
    {
      "lang": "nb-NO",
      "value": "Ta med hunden din ombord på toget."
    }
  ],
  "conditionsSummary": {
    "refundable": true,
    "exchangeable": true,
    "fareStructureType": "POINT_TO_POINT_FARE"
  },
  "purchaseWindowRef": "EXA:PurchaseWindow:90days",
  "chargingMomentType": "BEFORE_TRAVEL",
  "validityParameters": [
    {
      "groupingType": "OR",
      "validityParameterRefs": [
        "EXA:FareZone:A",
        "EXA:FareZone:B"
      ],
      "validityParameterType": "ZONE"
    }
  ],
  "ownerOrganisationId": 1,
  "supplementProductType": "DOG",
  "usageValidityPeriodRef": "EXA:UsageValidityPeriod:60minutes",
  "entitlementRequiredRefs": [
    "EXA:EntitlementRequired:StandardTicket"
  ]
}

json

application/json

Example Responses

{
  "id": "EXA:SupplementProduct:456",
  "names": [
    {
      "lang": "en-GB",
      "value": "Parking reservation"
    },
    {
      "lang": "nb-NO",
      "value": "Parkeringsreservasjon"
    }
  ],
  "status": "VERSIONED",
  "vatGroup": "TRANSPORT_AND_TICKETS_VAT",
  "farePrice": {
    "amount": 400,
    "currency": "NOK"
  },
  "startDate": "2025-01-01",
  "versionId": "EXA:Version:07ce871e-b84d-47c0-99ba-c7fdb5fa4df9",
  "datasource": {
    "id": "some-client-system"
  },
  "privateCode": "123",
  "descriptions": [
    {
      "lang": "en-GB",
      "value": "Reserve a parking spot at the station."
    },
    {
      "lang": "nb-NO",
      "value": "Reserver parkeringsplass på stasjonen."
    }
  ],
  "versionNumber": 1,
  "conditionsSummary": {
    "refundable": false,
    "exchangeable": false,
    "fareStructureType": "NETWORK_FLAT_FARE"
  },
  "purchaseWindowRef": "EXA:PurchaseWindow:120days",
  "chargingMomentType": "BEFORE_TRAVEL",
  "validityParameters": [
    {
      "groupingType": "OR",
      "validityParameterRefs": [
        "NSR:Parking:P01",
        "NSR:Parking:P02",
        "NSR:Parking:P03"
      ],
      "validityParameterType": "PARKING"
    }
  ],
  "ownerOrganisationId": 47,
  "supplementProductType": "PARKING",
  "usageValidityPeriodRef": "EXA:UsageValidityPeriod:30days",
  "entitlementRequiredRefs": [
    "EXA:EntitlementRequired:PeriodTicket30days"
  ]
}

json

application/json

List versions of a supplement product

GET

https://api.entur.io/products

/v3/supplement-products/{id}

Retrieve all versions of a supplement product by its NeTEx ID. Returns a lightweight list containing only the product ID and version ID for each version.

List versions of a supplement product › path Parameters

id

string · pattern: ^([A-Z]{3}):([A-Za-z… · required · style: simple

The netex ID of the element to retrieve

List versions of a supplement product › Headers

ET-Client-Name

string

X-Correlation-Id

string

Correlation id

List versions of a supplement product › Responses

List of supplement product versions

SupplementProductVersionListItem[]

SupplementProductVersionListItem

id

string · pattern: ^([A-Z]{3}):Suppleme… · required

NeTEx ID of the supplement product.

Example: EXA:SupplementProduct:456

versionId

string · pattern: ^([A-Z]{3}):Version:… · required

NeTEx version ID.

Example: EXA:Version:SP-abc123-v1

Create a new version of a supplement product

POST

https://api.entur.io/products

/v3/supplement-products/{id}

Create a new version of existing supplement product. The added version will be in DRAFT status, and will be created with version number n+1. The version will not be active until a start date is set and the version is published.

Create a new version of a supplement product › path Parameters

id

string · pattern: ^([A-Z]{3}):([A-Za-z… · required · style: simple

The netex ID of the element to retrieve

Create a new version of a supplement product › Headers

ET-Client-Name

string

X-Correlation-Id

string

Correlation id

Create a new version of a supplement product › Request Body

SupplementProductRequest

object[] · required

status

string · enum · required

Status of the supplement product. Defaults to VERSIONED.

DRAFT - Under construction and not ready for operational use.
PROPOSED - Complete but pending review and approval.
VERSIONED - Finalized and frozen; a new version must be created for further modifications. Remains authoritative for its validity period even after expiry.
DEPRECATED - Explicitly withdrawn and should not be used; indicates an active decision to retract, not a natural expiry.

Enum values:

DRAFT

PROPOSED

VERSIONED

DEPRECATED

Example: VERSIONED

vatGroup

VatGrpupType · enum · required

Enum values:

EXCEPTION_FROM_VAT

GENERAL_VAT

FOOD_VAT

TRANSPORT_AND_TICKETS_VAT

Default: TRANSPORT_AND_TICKETS_VAT

object · required

startDate

string · date · required

The start date of the version.

ConditionsSummary · required

purchaseWindowRef

string · pattern: ^([A-Z]{3}):Purchase… · required

NeTEx ID of a PurchaseWindow instance (limitations/purchase-window). Available values are listed in the Parameter Catalog API.

Example: ENT:PurchaseWindow:120days

chargingMomentType

ChargingMomentType · enum · required

Charging moment type.

Note: Currently, only BEFORE_TRAVEL is supported in Entur sales platform.

Enum values:

BEFORE_TRAVEL

ON_START_OF_TRAVEL

BEFORE_END_OF_TRAVEL

BEFORE_TRAVEL_THEN_ADJUST_AT_END_OF_TRAVEL

ON_START_THEN_ADJUST_AT_END_OF_TRAVEL

ON_START_THEN_ADJUST_AT_END_OF_FARE_DAY

ON_START_THEN_ADJUST_AT_END_OF_CHARGE_PERIOD

AT_END_OF_TRAVEL

ValidityParameters[] · required

List of validity parameters. The specified parameter tells where the supplement product is valid. This can be lines, zones, stops etc.

ownerOrganisationId

integer · int64 · required

The ID of the organization that owns the supplement product. Available organizations can be retrieved from the Organization Management API (external to this specification).

supplementProductType

SupplementProductType · enum · required

The type of the supplement product. This can be used to determine which parameters are relevant for the product.

Enum values:

SEAT_RESERVATION

BICYCLE

DOG

ANIMAL

MEAL

WIFI

EXTRA_LUGGAGE

PENALTY

usageValidityPeriodRef

string · pattern: ^([A-Z]{3}):UsageVal… · required

NeTEx ID of a UsageValidityPeriod instance (limitations/usage-validity-period). Available values are listed in the Parameter Catalog API.

Example: ENT:UsageValidityPeriod:DuringTravel

entitlementRequiredRefs

string[] · minItems: 1 · required

List of NeTEx IDs of EntitlementRequired instances (limitations/entitlement-required). Available values are listed in the Parameter Catalog API.

endDate

string · date

The end date of the version (optional).

privateCode

string

Example: 123

object[]

Create a new version of a supplement product › Responses

Supplement product created successfully

SupplementProductResponse

id

string · pattern: ^([A-Z]{3}):Suppleme… · required

The NeTEx ID of the supplement product.

Example: BNR:SupplementProduct:123

object[] · required

status

string · enum · required

Status of the supplement product.

DRAFT - Under construction and not ready for operational use.
PROPOSED - Complete but pending review and approval.
VERSIONED - Finalized and frozen; a new version must be created for further modifications. Remains authoritative for its validity period even after expiry.
DEPRECATED - Explicitly withdrawn and should not be used; indicates an active decision to retract, not a natural expiry.

Enum values:

DRAFT

PROPOSED

VERSIONED

DEPRECATED

Example: VERSIONED

vatGroup

VatGrpupType · enum · required

Enum values:

EXCEPTION_FROM_VAT

GENERAL_VAT

FOOD_VAT

TRANSPORT_AND_TICKETS_VAT

Default: TRANSPORT_AND_TICKETS_VAT

object · required

startDate

string · date · required

The start date of the version.

versionId

string · pattern: ^([A-Z]{3}):Version:… · required

The netex id reference to the object.

Example: EXA:Version:001

ConditionsSummary · required

purchaseWindowRef

string · pattern: ^([A-Z]{3}):Purchase… · required

NeTEx ID of a PurchaseWindow instance (limitations/purchase-window). Available values are listed in the Parameter Catalog API.

Example: ENT:PurchaseWindow:120days

chargingMomentType

ChargingMomentType · enum · required

Charging moment type.

Note: Currently, only BEFORE_TRAVEL is supported in Entur sales platform.

Enum values:

BEFORE_TRAVEL

ON_START_OF_TRAVEL

BEFORE_END_OF_TRAVEL

BEFORE_TRAVEL_THEN_ADJUST_AT_END_OF_TRAVEL

ON_START_THEN_ADJUST_AT_END_OF_TRAVEL

ON_START_THEN_ADJUST_AT_END_OF_FARE_DAY

ON_START_THEN_ADJUST_AT_END_OF_CHARGE_PERIOD

AT_END_OF_TRAVEL

ValidityParameters[] · required

List of validity parameters. The specified parameter tells where the supplement product is valid. This can be lines, zones, stops etc.

ownerOrganisationId

integer · int64 · required

The ID of the organization that owns the supplement product. Refer to your organization management service or documentation for how to obtain valid organization IDs.

supplementProductType

SupplementProductType · enum · required

The type of the supplement product. This can be used to determine which parameters are relevant for the product.

Enum values:

SEAT_RESERVATION

BICYCLE

DOG

ANIMAL

MEAL

WIFI

EXTRA_LUGGAGE

PENALTY

usageValidityPeriodRef

string · pattern: ^([A-Z]{3}):UsageVal… · required

NeTEx ID of a UsageValidityPeriod instance (limitations/usage-validity-period). Available values are listed in the Parameter Catalog API.

Example: ENT:UsageValidityPeriod:DuringTravel

entitlementRequiredRefs

string[] · minItems: 1 · required

List of NeTEx IDs of EntitlementRequired instances (limitations/entitlement-required). Available values are listed in the Parameter Catalog API.

endDate

string · date

The end date of the version (optional).

object

The datasource that owns this supplement product.

privateCode

string

Example: 123

object[]

versionNumber

integer · int64

Version number of the version. Only present when versionStatus is VERSIONED. Starts at 1 for a new product and is incremented by 1 for each new version.

Example: 1

POST/v3/supplement-products/{id}

curl https://api.entur.io/products/v3/supplement-products/:id \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "names": [
    {
      "lang": "en-GB",
      "value": "Dog"
    },
    {
      "lang": "nb-NO",
      "value": "Hund"
    }
  ],
  "status": "DRAFT",
  "vatGroup": "TRANSPORT_AND_TICKETS_VAT",
  "farePrice": {
    "amount": 30,
    "currency": "NOK"
  },
  "startDate": "2025-01-01",
  "descriptions": [
    {
      "lang": "en-GB",
      "value": "Bring your dog onboard the train."
    },
    {
      "lang": "nb-NO",
      "value": "Ta med hunden din ombord på toget."
    }
  ],
  "conditionsSummary": {
    "refundable": true,
    "exchangeable": true,
    "fareStructureType": "POINT_TO_POINT_FARE"
  },
  "purchaseWindowRef": "EXA:PurchaseWindow:90days",
  "chargingMomentType": "BEFORE_TRAVEL",
  "validityParameters": [
    {
      "groupingType": "OR",
      "validityParameterRefs": [
        "EXA:FareZone:A",
        "EXA:FareZone:B"
      ],
      "validityParameterType": "ZONE"
    }
  ],
  "ownerOrganisationId": 1,
  "supplementProductType": "DOG",
  "usageValidityPeriodRef": "EXA:UsageValidityPeriod:60minutes",
  "entitlementRequiredRefs": [
    "EXA:EntitlementRequired:StandardTicket"
  ]
}'

Example Request Body

{
  "names": [
    {
      "lang": "en-GB",
      "value": "Dog"
    },
    {
      "lang": "nb-NO",
      "value": "Hund"
    }
  ],
  "status": "DRAFT",
  "vatGroup": "TRANSPORT_AND_TICKETS_VAT",
  "farePrice": {
    "amount": 30,
    "currency": "NOK"
  },
  "startDate": "2025-01-01",
  "descriptions": [
    {
      "lang": "en-GB",
      "value": "Bring your dog onboard the train."
    },
    {
      "lang": "nb-NO",
      "value": "Ta med hunden din ombord på toget."
    }
  ],
  "conditionsSummary": {
    "refundable": true,
    "exchangeable": true,
    "fareStructureType": "POINT_TO_POINT_FARE"
  },
  "purchaseWindowRef": "EXA:PurchaseWindow:90days",
  "chargingMomentType": "BEFORE_TRAVEL",
  "validityParameters": [
    {
      "groupingType": "OR",
      "validityParameterRefs": [
        "EXA:FareZone:A",
        "EXA:FareZone:B"
      ],
      "validityParameterType": "ZONE"
    }
  ],
  "ownerOrganisationId": 1,
  "supplementProductType": "DOG",
  "usageValidityPeriodRef": "EXA:UsageValidityPeriod:60minutes",
  "entitlementRequiredRefs": [
    "EXA:EntitlementRequired:StandardTicket"
  ]
}

json

application/json

Example Responses

{
  "id": "EXA:SupplementProduct:456",
  "names": [
    {
      "lang": "en-GB",
      "value": "Parking reservation"
    },
    {
      "lang": "nb-NO",
      "value": "Parkeringsreservasjon"
    }
  ],
  "status": "VERSIONED",
  "vatGroup": "TRANSPORT_AND_TICKETS_VAT",
  "farePrice": {
    "amount": 400,
    "currency": "NOK"
  },
  "startDate": "2025-01-01",
  "versionId": "EXA:Version:07ce871e-b84d-47c0-99ba-c7fdb5fa4df9",
  "datasource": {
    "id": "some-client-system"
  },
  "privateCode": "123",
  "descriptions": [
    {
      "lang": "en-GB",
      "value": "Reserve a parking spot at the station."
    },
    {
      "lang": "nb-NO",
      "value": "Reserver parkeringsplass på stasjonen."
    }
  ],
  "versionNumber": 1,
  "conditionsSummary": {
    "refundable": false,
    "exchangeable": false,
    "fareStructureType": "NETWORK_FLAT_FARE"
  },
  "purchaseWindowRef": "EXA:PurchaseWindow:120days",
  "chargingMomentType": "BEFORE_TRAVEL",
  "validityParameters": [
    {
      "groupingType": "OR",
      "validityParameterRefs": [
        "NSR:Parking:P01",
        "NSR:Parking:P02",
        "NSR:Parking:P03"
      ],
      "validityParameterType": "PARKING"
    }
  ],
  "ownerOrganisationId": 47,
  "supplementProductType": "PARKING",
  "usageValidityPeriodRef": "EXA:UsageValidityPeriod:30days",
  "entitlementRequiredRefs": [
    "EXA:EntitlementRequired:PeriodTicket30days"
  ]
}

json

application/json

Get a supplement product version

GET

https://api.entur.io/products

/v3/supplement-products/{id}/{version}

Retrieve the complete supplement product for a specific version, identified by NeTEx version ID or version number.

Get a supplement product version › path Parameters

id

string · pattern: ^([A-Z]{3}):([A-Za-z… · required · style: simple

The netex ID of the element to retrieve

version

string · pattern: ^(([A-Z]{3}):Version… · required · style: simple

The netex ID or sequence number of the version to retrieve

Get a supplement product version › Headers

ET-Client-Name

string

X-Correlation-Id

string

Correlation id

Get a supplement product version › Responses

Supplement product version found

SupplementProductResponse

id

string · pattern: ^([A-Z]{3}):Suppleme… · required

The NeTEx ID of the supplement product.

Example: BNR:SupplementProduct:123

object[] · required

status

string · enum · required

Status of the supplement product.

DRAFT - Under construction and not ready for operational use.
PROPOSED - Complete but pending review and approval.
VERSIONED - Finalized and frozen; a new version must be created for further modifications. Remains authoritative for its validity period even after expiry.
DEPRECATED - Explicitly withdrawn and should not be used; indicates an active decision to retract, not a natural expiry.

Enum values:

DRAFT

PROPOSED

VERSIONED

DEPRECATED

Example: VERSIONED

vatGroup

VatGrpupType · enum · required

Enum values:

EXCEPTION_FROM_VAT

GENERAL_VAT

FOOD_VAT

TRANSPORT_AND_TICKETS_VAT

Default: TRANSPORT_AND_TICKETS_VAT

object · required

startDate

string · date · required

The start date of the version.

versionId

string · pattern: ^([A-Z]{3}):Version:… · required

The netex id reference to the object.

Example: EXA:Version:001

ConditionsSummary · required

purchaseWindowRef

string · pattern: ^([A-Z]{3}):Purchase… · required

NeTEx ID of a PurchaseWindow instance (limitations/purchase-window). Available values are listed in the Parameter Catalog API.

Example: ENT:PurchaseWindow:120days

chargingMomentType

ChargingMomentType · enum · required

Charging moment type.

Note: Currently, only BEFORE_TRAVEL is supported in Entur sales platform.

Enum values:

BEFORE_TRAVEL

ON_START_OF_TRAVEL

BEFORE_END_OF_TRAVEL

BEFORE_TRAVEL_THEN_ADJUST_AT_END_OF_TRAVEL

ON_START_THEN_ADJUST_AT_END_OF_TRAVEL

ON_START_THEN_ADJUST_AT_END_OF_FARE_DAY

ON_START_THEN_ADJUST_AT_END_OF_CHARGE_PERIOD

AT_END_OF_TRAVEL

ValidityParameters[] · required

List of validity parameters. The specified parameter tells where the supplement product is valid. This can be lines, zones, stops etc.

ownerOrganisationId

integer · int64 · required

The ID of the organization that owns the supplement product. Refer to your organization management service or documentation for how to obtain valid organization IDs.

supplementProductType

SupplementProductType · enum · required

The type of the supplement product. This can be used to determine which parameters are relevant for the product.

Enum values:

SEAT_RESERVATION

BICYCLE

DOG

ANIMAL

MEAL

WIFI

EXTRA_LUGGAGE

PENALTY

usageValidityPeriodRef

string · pattern: ^([A-Z]{3}):UsageVal… · required

NeTEx ID of a UsageValidityPeriod instance (limitations/usage-validity-period). Available values are listed in the Parameter Catalog API.

Example: ENT:UsageValidityPeriod:DuringTravel

entitlementRequiredRefs

string[] · minItems: 1 · required

List of NeTEx IDs of EntitlementRequired instances (limitations/entitlement-required). Available values are listed in the Parameter Catalog API.

endDate

string · date

The end date of the version (optional).

object

The datasource that owns this supplement product.

privateCode

string

Example: 123

object[]

versionNumber

integer · int64

Version number of the version. Only present when versionStatus is VERSIONED. Starts at 1 for a new product and is incremented by 1 for each new version.

Example: 1

GET/v3/supplement-products/{id}/{version}

curl https://api.entur.io/products/v3/supplement-products/:id/:version \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "id": "EXA:SupplementProduct:456",
  "names": [
    {
      "lang": "en-GB",
      "value": "Parking reservation"
    },
    {
      "lang": "nb-NO",
      "value": "Parkeringsreservasjon"
    }
  ],
  "status": "VERSIONED",
  "vatGroup": "TRANSPORT_AND_TICKETS_VAT",
  "farePrice": {
    "amount": 400,
    "currency": "NOK"
  },
  "startDate": "2025-01-01",
  "versionId": "EXA:Version:07ce871e-b84d-47c0-99ba-c7fdb5fa4df9",
  "datasource": {
    "id": "some-client-system"
  },
  "privateCode": "123",
  "descriptions": [
    {
      "lang": "en-GB",
      "value": "Reserve a parking spot at the station."
    },
    {
      "lang": "nb-NO",
      "value": "Reserver parkeringsplass på stasjonen."
    }
  ],
  "versionNumber": 1,
  "conditionsSummary": {
    "refundable": false,
    "exchangeable": false,
    "fareStructureType": "NETWORK_FLAT_FARE"
  },
  "purchaseWindowRef": "EXA:PurchaseWindow:120days",
  "chargingMomentType": "BEFORE_TRAVEL",
  "validityParameters": [
    {
      "groupingType": "OR",
      "validityParameterRefs": [
        "NSR:Parking:P01",
        "NSR:Parking:P02",
        "NSR:Parking:P03"
      ],
      "validityParameterType": "PARKING"
    }
  ],
  "ownerOrganisationId": 47,
  "supplementProductType": "PARKING",
  "usageValidityPeriodRef": "EXA:UsageValidityPeriod:30days",
  "entitlementRequiredRefs": [
    "EXA:EntitlementRequired:PeriodTicket30days"
  ]
}

json

application/json

Update a version of a supplement product

PUT

https://api.entur.io/products

/v3/supplement-products/{id}/{version}

Update the version of a supplement product. The version will not be active until a start date is set and the version is published.

Update a version of a supplement product › path Parameters

id

string · pattern: ^([A-Z]{3}):([A-Za-z… · required · style: simple

The netex ID of the element to retrieve

version

string · pattern: ^(([A-Z]{3}):Version… · required · style: simple

The netex ID or sequence number of the version to retrieve

Update a version of a supplement product › Headers

ET-Client-Name

string

X-Correlation-Id

string

Correlation id

Update a version of a supplement product › Request Body

SupplementProductRequest

object[] · required

status

string · enum · required

Status of the supplement product. Defaults to VERSIONED.

DRAFT - Under construction and not ready for operational use.
PROPOSED - Complete but pending review and approval.
VERSIONED - Finalized and frozen; a new version must be created for further modifications. Remains authoritative for its validity period even after expiry.
DEPRECATED - Explicitly withdrawn and should not be used; indicates an active decision to retract, not a natural expiry.

Enum values:

DRAFT

PROPOSED

VERSIONED

DEPRECATED

Example: VERSIONED

vatGroup

VatGrpupType · enum · required

Enum values:

EXCEPTION_FROM_VAT

GENERAL_VAT

FOOD_VAT

TRANSPORT_AND_TICKETS_VAT

Default: TRANSPORT_AND_TICKETS_VAT

object · required

startDate

string · date · required

The start date of the version.

ConditionsSummary · required

purchaseWindowRef

string · pattern: ^([A-Z]{3}):Purchase… · required

NeTEx ID of a PurchaseWindow instance (limitations/purchase-window). Available values are listed in the Parameter Catalog API.

Example: ENT:PurchaseWindow:120days

chargingMomentType

ChargingMomentType · enum · required

Charging moment type.

Note: Currently, only BEFORE_TRAVEL is supported in Entur sales platform.

Enum values:

BEFORE_TRAVEL

ON_START_OF_TRAVEL

BEFORE_END_OF_TRAVEL

BEFORE_TRAVEL_THEN_ADJUST_AT_END_OF_TRAVEL

ON_START_THEN_ADJUST_AT_END_OF_TRAVEL

ON_START_THEN_ADJUST_AT_END_OF_FARE_DAY

ON_START_THEN_ADJUST_AT_END_OF_CHARGE_PERIOD

AT_END_OF_TRAVEL

ValidityParameters[] · required

List of validity parameters. The specified parameter tells where the supplement product is valid. This can be lines, zones, stops etc.

ownerOrganisationId

integer · int64 · required

The ID of the organization that owns the supplement product. Available organizations can be retrieved from the Organization Management API (external to this specification).

supplementProductType

SupplementProductType · enum · required

The type of the supplement product. This can be used to determine which parameters are relevant for the product.

Enum values:

SEAT_RESERVATION

BICYCLE

DOG

ANIMAL

MEAL

WIFI

EXTRA_LUGGAGE

PENALTY

usageValidityPeriodRef

string · pattern: ^([A-Z]{3}):UsageVal… · required

NeTEx ID of a UsageValidityPeriod instance (limitations/usage-validity-period). Available values are listed in the Parameter Catalog API.

Example: ENT:UsageValidityPeriod:DuringTravel

entitlementRequiredRefs

string[] · minItems: 1 · required

List of NeTEx IDs of EntitlementRequired instances (limitations/entitlement-required). Available values are listed in the Parameter Catalog API.

endDate

string · date

The end date of the version (optional).

privateCode

string

Example: 123

object[]

Update a version of a supplement product › Responses

Supplement product updated successfully

SupplementProductResponse

id

string · pattern: ^([A-Z]{3}):Suppleme… · required

The NeTEx ID of the supplement product.

Example: BNR:SupplementProduct:123

object[] · required

status

string · enum · required

Status of the supplement product.

DRAFT - Under construction and not ready for operational use.
PROPOSED - Complete but pending review and approval.
VERSIONED - Finalized and frozen; a new version must be created for further modifications. Remains authoritative for its validity period even after expiry.
DEPRECATED - Explicitly withdrawn and should not be used; indicates an active decision to retract, not a natural expiry.

Enum values:

DRAFT

PROPOSED

VERSIONED

DEPRECATED

Example: VERSIONED

vatGroup

VatGrpupType · enum · required

Enum values:

EXCEPTION_FROM_VAT

GENERAL_VAT

FOOD_VAT

TRANSPORT_AND_TICKETS_VAT

Default: TRANSPORT_AND_TICKETS_VAT

object · required

startDate

string · date · required

The start date of the version.

versionId

string · pattern: ^([A-Z]{3}):Version:… · required

The netex id reference to the object.

Example: EXA:Version:001

ConditionsSummary · required

purchaseWindowRef

string · pattern: ^([A-Z]{3}):Purchase… · required

NeTEx ID of a PurchaseWindow instance (limitations/purchase-window). Available values are listed in the Parameter Catalog API.

Example: ENT:PurchaseWindow:120days

chargingMomentType

ChargingMomentType · enum · required

Charging moment type.

Note: Currently, only BEFORE_TRAVEL is supported in Entur sales platform.

Enum values:

BEFORE_TRAVEL

ON_START_OF_TRAVEL

BEFORE_END_OF_TRAVEL

BEFORE_TRAVEL_THEN_ADJUST_AT_END_OF_TRAVEL

ON_START_THEN_ADJUST_AT_END_OF_TRAVEL

ON_START_THEN_ADJUST_AT_END_OF_FARE_DAY

ON_START_THEN_ADJUST_AT_END_OF_CHARGE_PERIOD

AT_END_OF_TRAVEL

ValidityParameters[] · required

List of validity parameters. The specified parameter tells where the supplement product is valid. This can be lines, zones, stops etc.

ownerOrganisationId

integer · int64 · required

The ID of the organization that owns the supplement product. Refer to your organization management service or documentation for how to obtain valid organization IDs.

supplementProductType

SupplementProductType · enum · required

The type of the supplement product. This can be used to determine which parameters are relevant for the product.

Enum values:

SEAT_RESERVATION

BICYCLE

DOG

ANIMAL

MEAL

WIFI

EXTRA_LUGGAGE

PENALTY

usageValidityPeriodRef

string · pattern: ^([A-Z]{3}):UsageVal… · required

NeTEx ID of a UsageValidityPeriod instance (limitations/usage-validity-period). Available values are listed in the Parameter Catalog API.

Example: ENT:UsageValidityPeriod:DuringTravel

entitlementRequiredRefs

string[] · minItems: 1 · required

List of NeTEx IDs of EntitlementRequired instances (limitations/entitlement-required). Available values are listed in the Parameter Catalog API.

endDate

string · date

The end date of the version (optional).

object

The datasource that owns this supplement product.

privateCode

string

Example: 123

object[]

versionNumber

integer · int64

Version number of the version. Only present when versionStatus is VERSIONED. Starts at 1 for a new product and is incremented by 1 for each new version.

Example: 1

PUT/v3/supplement-products/{id}/{version}

curl https://api.entur.io/products/v3/supplement-products/:id/:version \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "names": [
    {
      "lang": "en-GB",
      "value": "Dog"
    },
    {
      "lang": "nb-NO",
      "value": "Hund"
    }
  ],
  "status": "DRAFT",
  "vatGroup": "TRANSPORT_AND_TICKETS_VAT",
  "farePrice": {
    "amount": 30,
    "currency": "NOK"
  },
  "startDate": "2025-01-01",
  "descriptions": [
    {
      "lang": "en-GB",
      "value": "Bring your dog onboard the train."
    },
    {
      "lang": "nb-NO",
      "value": "Ta med hunden din ombord på toget."
    }
  ],
  "conditionsSummary": {
    "refundable": true,
    "exchangeable": true,
    "fareStructureType": "POINT_TO_POINT_FARE"
  },
  "purchaseWindowRef": "EXA:PurchaseWindow:90days",
  "chargingMomentType": "BEFORE_TRAVEL",
  "validityParameters": [
    {
      "groupingType": "OR",
      "validityParameterRefs": [
        "EXA:FareZone:A",
        "EXA:FareZone:B"
      ],
      "validityParameterType": "ZONE"
    }
  ],
  "ownerOrganisationId": 1,
  "supplementProductType": "DOG",
  "usageValidityPeriodRef": "EXA:UsageValidityPeriod:60minutes",
  "entitlementRequiredRefs": [
    "EXA:EntitlementRequired:StandardTicket"
  ]
}'

Example Request Body

{
  "names": [
    {
      "lang": "en-GB",
      "value": "Dog"
    },
    {
      "lang": "nb-NO",
      "value": "Hund"
    }
  ],
  "status": "DRAFT",
  "vatGroup": "TRANSPORT_AND_TICKETS_VAT",
  "farePrice": {
    "amount": 30,
    "currency": "NOK"
  },
  "startDate": "2025-01-01",
  "descriptions": [
    {
      "lang": "en-GB",
      "value": "Bring your dog onboard the train."
    },
    {
      "lang": "nb-NO",
      "value": "Ta med hunden din ombord på toget."
    }
  ],
  "conditionsSummary": {
    "refundable": true,
    "exchangeable": true,
    "fareStructureType": "POINT_TO_POINT_FARE"
  },
  "purchaseWindowRef": "EXA:PurchaseWindow:90days",
  "chargingMomentType": "BEFORE_TRAVEL",
  "validityParameters": [
    {
      "groupingType": "OR",
      "validityParameterRefs": [
        "EXA:FareZone:A",
        "EXA:FareZone:B"
      ],
      "validityParameterType": "ZONE"
    }
  ],
  "ownerOrganisationId": 1,
  "supplementProductType": "DOG",
  "usageValidityPeriodRef": "EXA:UsageValidityPeriod:60minutes",
  "entitlementRequiredRefs": [
    "EXA:EntitlementRequired:StandardTicket"
  ]
}

json

application/json

Example Responses

{
  "id": "EXA:SupplementProduct:456",
  "names": [
    {
      "lang": "en-GB",
      "value": "Parking reservation"
    },
    {
      "lang": "nb-NO",
      "value": "Parkeringsreservasjon"
    }
  ],
  "status": "VERSIONED",
  "vatGroup": "TRANSPORT_AND_TICKETS_VAT",
  "farePrice": {
    "amount": 400,
    "currency": "NOK"
  },
  "startDate": "2025-01-01",
  "versionId": "EXA:Version:07ce871e-b84d-47c0-99ba-c7fdb5fa4df9",
  "datasource": {
    "id": "some-client-system"
  },
  "privateCode": "123",
  "descriptions": [
    {
      "lang": "en-GB",
      "value": "Reserve a parking spot at the station."
    },
    {
      "lang": "nb-NO",
      "value": "Reserver parkeringsplass på stasjonen."
    }
  ],
  "versionNumber": 1,
  "conditionsSummary": {
    "refundable": false,
    "exchangeable": false,
    "fareStructureType": "NETWORK_FLAT_FARE"
  },
  "purchaseWindowRef": "EXA:PurchaseWindow:120days",
  "chargingMomentType": "BEFORE_TRAVEL",
  "validityParameters": [
    {
      "groupingType": "OR",
      "validityParameterRefs": [
        "NSR:Parking:P01",
        "NSR:Parking:P02",
        "NSR:Parking:P03"
      ],
      "validityParameterType": "PARKING"
    }
  ],
  "ownerOrganisationId": 47,
  "supplementProductType": "PARKING",
  "usageValidityPeriodRef": "EXA:UsageValidityPeriod:30days",
  "entitlementRequiredRefs": [
    "EXA:EntitlementRequired:PeriodTicket30days"
  ]
}

json

application/json

Purchase Window Sales package assignment

Build with Entur

Contribute

Terms & Policies

Supplement product

Create a new supplement product

Create a new supplement product › Headers

Create a new supplement product › Request Body

Create a new supplement product › Responses

List versions of a supplement product

List versions of a supplement product › path Parameters

List versions of a supplement product › Headers

List versions of a supplement product › Responses

Create a new version of a supplement product

Create a new version of a supplement product › path Parameters

Create a new version of a supplement product › Headers

Create a new version of a supplement product › Request Body

Create a new version of a supplement product › Responses

Get a supplement product version

Get a supplement product version › path Parameters

Get a supplement product version › Headers

Get a supplement product version › Responses

Update a version of a supplement product

Update a version of a supplement product › path Parameters

Update a version of a supplement product › Headers

Update a version of a supplement product › Request Body

Update a version of a supplement product › Responses