Displays On Demand meters every operation in credits. This page explains the credit costs, idempotency guarantees, refund behavior, and the subscription window for direct-add profile access.

All endpoints are on the v2 base https://api2.mworks.com under the /v2/displays/* path. For the full endpoint reference, see Displays API reference.

Credit model

Every asset-library endpoint carries a base cost of 1 credit (displays_asset_crud). On top of the base cost, measurement purchases charge additional credits based on the measurement kind:

So a full lifecycle for one asset costs: 1 cr (create) + 1 cr (queue draft) + 150 cr (draft purchase) + 1 cr (queue final) + 300 cr (final purchase) = 453 credits, plus any read/list/summary calls at 1 cr each.

Idempotency

The two purchase-style endpoints have different retry contracts (ADR-0042):

• POST /v2/displays/assets (create) takes no idempotency key and returns 200 synchronously. A retry creates a second asset. The only duplicate protection is the 409 duplicate-face guard, which fires when your organization already has an asset with the same party_display_id and spot_id (carried in related_parties[owner]). Both fields are optional, so send them whenever you have them; without them a retried create silently produces a duplicate.
• POST .../measurements carries the idempotency key in the request body as measurement_request_id (a UUID). The Idempotency-Key header is rejected with 400. Replaying the same measurement_request_id with the same body returns the original 202 result without queuing a second measurement or charging a second purchase. Replaying the same id with a different body returns 409 idempotency_mismatch.

Verified (MA-107, 2026-08-31): replay of a measurement purchase with the same measurement_request_id returned the original queued result with no second charge.

Informational-outcome auto-refund

Some measurement results are informational rather than measured. When a draft or final measurement completes with one of these outcomes, the purchase charge is automatically refunded:

• no_coverage: the face's viewshed has no traffic coverage in the source data. No measured impressions are available.
• insufficient_data: the source data for the viewshed is too sparse to produce a reliable measurement.

In both cases the measurement result is delivered (status completed with the informational outcome in the result body), but the purchase credits (150 for draft, 300 for final) are returned to your account. The refund_credits field in the measurement result reflects the refunded amount. The base 1 cr endpoint cost is not refunded.

Failed-state refund

If a measurement enters the failed state (the measurement pipeline could not produce any result, informational or otherwise), the purchase charge is also automatically refunded. The refund_credits field in the failed result reflects the refunded amount. The base 1 cr endpoint cost is not refunded.

The 12-month subscription window and day-366 renewal

When you call GET /v2/displays/profiles/{viewshed_id} for a viewshed that your organization does not own but that is public, final_measured, and non-archived, the API charges 300 credits (displays_viewshed_purchase_direct) and auto-adds the face to your organization. This starts a 12-month subscription window for that viewshed.

• For the next 12 months, GET /v2/displays/profiles/{viewshed_id} for that viewshed costs only the base 1 cr (owned read).
• On day 366, the subscription renews automatically at the same price (300 credits). The renewal charge extends the window for another 12 months.

If you do not want the subscription to renew, archive the asset or remove the face from your organization's inventory before day 366.

Viewsheds that are unknown, private, archived, or not in final_measured state return 404 (never 403) on the profile endpoint. This means the API does not leak the existence of private or archived inventory to unlicensed callers.

Verified (MA-99): the profile endpoint returned 404 for an unknown viewshed_id; entitlements for the canary pay-as-you-go org allowed direct-add.

What to read next

• Asset lifecycle
• Measurements
• Methodology delta
• Displays Search
• Displays API reference