Purchase

The Purchase API lets you register, track, and manage access to purchased digital assets.

It is designed as a fully asynchronous workflow, allowing your integration to remain reliable in the presence of retries, delays, and external business events.

Use this API to convert catalog assets into completed purchases and control access throughout the asset lifecycle.

---

High-level flow

flowchart TD
    A[Asset sold on vendor side] --> B[POST /purchase/register]
    B --> C{Order status}

    C -->|PROCESSING| D[GET /purchase/info]
    D --> C

    C -->|COMPLETED| E[Access asset]
    C -->|FAILED| F[Handle failure]

---

Purchase model

Purchases follow an order-based model:

• A purchase is registered for a specific asset
• The system creates a vendor order
• Fulfillment happens asynchronously
• Orders transition through well-defined statuses
• Assets become available after completion
• Access can be explicitly revoked by the vendor

This model allows long-running processing while keeping your integration responsive.

---

Register a purchase

To start a purchase, register a new order for a catalog asset.

POST /purchase/register

What happens

• Request parameters are validated
• A new order is created
• Fulfillment starts asynchronously
• A vendor order ID is assigned

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

---

Track purchase status

Use the purchase info endpoint to retrieve the current state of an order.

GET /purchase/info

Depending on the processing state, the response may vary.

Possible outcomes

• PROCESSING — order fulfillment is still in progress
• COMPLETED — order is fulfilled and assets are available
• FAILED — order fulfillment failed

This allows you to implement polling and retry logic on your side.

---

Order statuses

Status	Description
PROCESSING	Order is being fulfilled
FAILED	Order fulfillment failed
COMPLETED	Order successfully fulfilled
CANCELED	Order was canceled by the vendor

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

---

Access purchased assets

Once an order is completed, assets can be accessed using secure URLs.

Download URL

GET /purchase/download-url

Returns a secure URL for downloading the asset file.

View URL

GET /purchase/view-url

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

---

Cancel a purchase

Vendors may explicitly cancel a purchase at any time.

DELETE /purchase/cancel

Cancellation is a vendor-initiated action and represents an authoritative request to revoke access to the purchased asset.

What cancellation does

• Revokes access to the asset
• Invalidates existing download and view URLs
• Transitions the order state to CANCELED

The API does not apply additional business validation to cancellation requests.

---

Error handling

The Purchase API uses standard HTTP status codes:

• 401 — authentication required or invalid token
• 404 — asset or order not found
• 409 — duplicate purchase registration
• 422 — request validation failed
• 5xx — internal or upstream processing errors

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