Entur Developer
Fare data

Versions and lifecycle

You change fare data by creating a new version of an element and sending it through a lifecycle: draft, test in the staging environment, and published in production. Each version has effective dates that say which travel dates it applies to. The API enforces the rules between elements, so a product can never be published with rules that are not published for the same dates.

Elements, versions and effective dates

Three concepts work together. They are related, but they are not the same thing:

  • An element is a product, a parameter, a fare table or a sales package. It has a stable NeTEx id, id, for example EXA:PurchaseWindow:1b7d4c2a. Other elements refer to it by this id.
  • A version is one edition of the element's content. You create a version, edit it while it is a draft, and send it through the lifecycle. A version is identified by versionId, which is {version} in paths. When it is published, it gets a version number, versionNumber.
  • The effective dates, validBetween, are the travel dates a version applies to. You set them when you send the version to test and when you publish it.

An element has one or more versions, and each version has one set of effective dates. The effective dates say which travel days the version is valid for.

Effective dates (validBetween)

The effective dates are written like this:

JSONCode
{ "validBetween": { "fromDate": "2027-01-01", "toDate": "2027-06-30" } }
  • fromDate is the first day the version applies.
  • toDate is the last day the version applies. The date is inclusive. Leave it out for a version with no end.
  • The dates are about travel. They say when a product can be used, not when it can be sold.

A version keeps its id when you change its effective dates. You can propose a version again with other dates, and you can end a published version with expire. It is still the same version.

The effective dates of an element's published versions follow each other with no overlaps and no gaps. A version that follows another starts on the day after the earlier version's toDate:

Version numberfromDatetoDate
12027-01-012027-06-30
22027-07-01(open)

Statuses

A version has one of four statuses. The status says which Entur environment the version is available in:

StatusAvailable in environmentCan you change the content?
DRAFTNone. Work in progress.Yes
PROPOSEDStaging, for testing.No
VERSIONEDProduction. This is the published status.No
DEPRECATEDNone. Replaced by another version. Set by the API, never by you.No

You create all fare data in the production API. The status decides where it is used: a PROPOSED version is only used in the staging environment, so you can test it before it reaches travellers.

Some rules follow from the statuses:

  • Only a DRAFT version can be changed (PUT) or deleted (DELETE).
  • To change something that is under test or published, create a new version with POST /{id}. A new version doesn't inherit anything from earlier versions, so send the complete content, including all references. It starts as a DRAFT.
  • An element can have only one version in progress (DRAFT or PROPOSED) at a time.

Operations

A version moves between statuses through four operations. Each one is a POST to /{id}/{version}/<operation> on the element:

OperationAllowed fromResulting statusRequest body
proposeDRAFT, PROPOSEDPROPOSEDvalidBetween (required)
withdrawPROPOSEDDRAFTOptional
publishPROPOSEDVERSIONEDvalidBetween (required)
expireVERSIONEDVERSIONEDtoDate (required)

create version

propose

propose (new effective dates)

withdraw

publish

expire

replaced (automatic)

delete

DRAFT

PROPOSED

VERSIONED

DEPRECATED

What each operation does:

  • propose makes the version available in the staging environment, with the effective dates you give it.
  • withdraw takes the version out of staging and back to DRAFT, so you can change it.
  • publish makes the version available in the production environment and gives it a version number. You give the effective dates again. The dates you used for testing are not carried over. fromDate can't be in the past. Today is allowed.
  • expire sets the last effective date (toDate) of a published version. It can't be in the past. The fromDate of a published version can't change.

All four operations also take note, externalReferenceName and externalReferenceUrl. These are written to the element's audit log. Use them to record why you made the change, for example with a link to your own case.

When you publish a version, the API keeps the effective dates of the published versions continuous:

  • If the previous published version has no end, the API sets its toDate to the day before the new version's fromDate.
  • If the previous published version has exactly the same effective dates, the API sets it to DEPRECATED.

Both changes are written to the audit log as automatic changes.

Coverage rule

A product refers to rules and parameters, such as a purchase window or a usage validity period (how long the product can be used after purchase or activation). It refers to them by NeTEx id, not by version. On each travel date, the product uses the published version of the parameter whose effective dates include that date.

The API therefore checks that each parameter has published versions for all of the product's effective dates. The full check is made when you publish:

WhenWhat is checked
You create or update a draftOnly that each referenced parameter exists
You propose the productNothing more than for a draft
You publish the productThe effective dates of the parameters' published versions together cover the product's effective dates, and the product has a usage validity period

The coverage rule is checked when you publish. A product with no toDate needs parameters with no toDate too.

Propose the parameters before the product anyway, so that everything the product depends on is available in the staging environment while you test.

The rule works in both directions. You can't end a published parameter earlier than a published product that depends on it.

Publish order

Because of the coverage rule, work from the bottom up. Publish what a product depends on before the product, and the product before the sales packages that contain it.

Rules and parameters

Prices
FareTable

Product

Sales package
SalesOfferPackage

  1. Propose the parameters, the prices and the product, in that order.
  2. Propose the sales package that contains the product. A sales package refers to a specific version of the product by its versionId.
  3. Test the whole package in staging. Travellers buy sales packages, so this is the first point where you can try a purchase.
  4. Publish in the same order: parameters, prices, product, sales package.

If you publish a product before a parameter it refers to, the API rejects the request with the coverage error shown in Errors.

Price changes

A product refers to its fare tables by NeTEx id, not by version. When a new version of a fare table becomes valid, the product uses the new prices from that day. The product doesn't need a new version.

To change a price, create a new version of the fare table with the new price and a fromDate for when it applies, then propose and publish it.

Other operators can include your products in their own sales packages. When you change a product or its prices, the change also applies wherever your product is sold together with theirs.

Errors

The API returns errors as RFC 9457 problem details, with content type application/problem+json. The detail field says what went wrong. When the error is about a parameter the request refers to, the response also has field, the field in your request, and reference, the id that failed:

JSONCode
{ "title": "Invalid parameter reference", "status": 400, "detail": "purchaseWindowRef 'EXA:PurchaseWindow:7d2e…': Eligible parameter versions do not cover 2027-01-01 to open end for VERSIONED", "field": "purchaseWindowRef", "reference": "EXA:PurchaseWindow:7d2e…" }

Most errors come from the rules on this page:

StatusTypical causeSee
400A referenced parameter doesn't exist, or isn't published for all of the product's effective dates.Coverage rule
400The effective dates are invalid, for example reversed or starting in the past when you publish.Effective dates
409The operation isn't allowed from the version's status, the element already has a version in progress, or you tried to change a version that isn't a draft.Statuses, Operations
409The effective dates overlap or leave a gap to another published version.Effective dates
403The element belongs to another organisation.Fare data – Access
Last modified on
Did you find what you were looking for?