After an asset is sold

This guide explains how to register a completed sale in HL Connect 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 Connect about the purchase and then track its processing status until completion.

Overview

Once an asset is sold on the vendor side:

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

Step 1 — Validate the purchase

Before you process the payment on your side, it's highly recommended to validate the purchase. This ensures that the asset is available for sale and that the customer is eligible to purchase it (e.g., they are not in a restricted region).

If validation is successful, you will receive a validation token and an expiration timestamp (exp_date). This token is short-lived, one-time use, and must be passed to the registration endpoint in the next step.

Step 2 — Register the purchase

After the asset is sold (and payment is confirmed), register the purchase in HL Connect using the token obtained in Step 1.

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

What happens

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

Step 3 — 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 4 — 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 Customer
    participant Vendor
    participant HL as HL Connect

    Customer->>Vendor: Wants to buy asset
    Vendor->>HL: POST /purchase/validate-purchase-before-payment
    HL-->>Vendor: 200 OK (token, exp_date)
    Vendor->>Customer: Proceed to payment
    Customer->>Vendor: Payment successful
    Vendor->>HL: POST /purchase/register (token)
    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:

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

Summary