After an asset is sold

This guide explains how to register a completed sale in HL Connector and track fulfillment until the asset becomes available.

The Purchase API is asynchronous by design. After a sale happens on your side, you notify HL Connector about the purchase and then track its processing status until completion.

Overview

Once an asset is sold on the vendor side:

The vendor registers the purchase in HL Connector
HL Connector creates an order and starts fulfillment
The vendor polls the order status
After completion, the asset becomes available
If required, access can later be revoked by the vendor

This flow allows HL Connector to safely handle retries, delays, and external business events without blocking your system.

Client API Token

Step 1 — Register the purchase

After the asset is sold, register the purchase in HL Connector.

This request notifies HL Connector that an asset was sold and that fulfillment should begin.

What happens

Request parameters are validated
A new vendor order is created
Fulfillment starts asynchronously
The request returns immediately

If an order already exists for the same parameters, the API returns a 409 Conflict response.

Step 2 — Track order processing

Fulfillment does not complete immediately. Use the order info endpoint to check the current status.

Possible responses

Status	Meaning
`202`	Order is still processing
`200`	Order completed, assets are available
`502`	Fulfillment failed
`404`	Order not found

Your integration is expected to poll this endpoint until the order reaches a terminal state.

Order lifecycle

Status	Description
`PROCESSING`	Fulfillment is in progress
`COMPLETED`	Order fulfilled, access granted
`FAILED`	Fulfillment failed
`CANCELED`	Access revoked by the vendor

Status values are stable and safe to persist in your system.

Step 3 — Access the asset

Once an order reaches COMPLETED, assets become accessible using secure URLs.

Download the asset

Returns a secure URL for downloading the asset file.

View the asset online

Returns a secure URL for online viewing (for example, a sheet music viewer).

Vendor-initiated cancellation

If access to an asset must be revoked due to a business event on the vendor side, the vendor can cancel a specific order line item.

Cancellation updates the order state and revokes access to the asset.

Common integration pattern

sequenceDiagram
    participant Vendor
    participant HL as HL Connector

    Vendor->>HL: POST /purchase/register
    HL-->>Vendor: 201 Created

    loop Until completed
        Vendor->>HL: GET /purchase/info
        HL-->>Vendor: PROCESSING
    end

    HL-->>Vendor: COMPLETED

Error handling

The Purchase API uses standard HTTP status codes:

401 — missing or invalid access token
404 — asset or order not found
409 — duplicate purchase registration
422 — request validation failed
5xx — fulfillment or internal errors

Errors are returned in a structured JSON format and are safe to log or display.

Summary

Register each completed sale using /purchase/register
Treat fulfillment as asynchronous
Poll /purchase/info until a terminal state is reached
Grant access only after COMPLETED
Revoke access using /purchase/cancel when needed