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[Customer wants to buy asset] --> B[POST /purchase/validate-purchase-before-payment]
    B --> C{Validation successful?}
    C -->|No| D[Display error to customer]
    C -->|Yes| E[Initiate payment on vendor side]
    E --> F[Payment successful]
    F --> G[POST /purchase/register]
    G --> H{Order status}

    H -->|PROCESSING| I[GET /purchase/info]
    I --> H

    H -->|COMPLETED| J[Access asset]
    H -->|FAILED| K[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.

---

Validate a purchase

Before initiating a payment, you should validate the purchase to ensure the asset is available and the customer is eligible to buy it (e.g., based on their region).

POST /purchase/validate-purchase-before-payment

What happens

• Asset availability is checked
• Regional restrictions are validated based on the customer's IP
• Minimum quantity requirements are verified
• A short-lived, one-time validation token is generated

If validation fails, the API returns a 400 Bad Request with a specific error code. If successful, you receive a token and its expiration timestamp (exp_date). The token must be provided during purchase registration.

---

Register a purchase

To start a purchase, register a new order for a catalog asset using the token obtained from the validation step.

POST /purchase/register

What happens

• The validation token is verified (must be valid, not expired, and not used before)
• Request parameters are validated
• A new order is created
• Fulfillment starts asynchronously
• A vendor order ID is assigned
• The validation token is consumed and cannot be used again

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:

• 400 — bad request (e.g., validation failed, region not allowed)
• 401 — authentication required or invalid token
• 404 — asset or order not found
• 409 — duplicate purchase registration
• 422 — request validation failed (e.g., expired or already used validation token)
• 5xx — internal or upstream processing errors

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