Commerce & Licensing API

Track purchases, license certificates, exclusive license presets, and safe producer finance references.

Overview

The Commerce & Licensing API handles the complete purchase lifecycle - from pricing calculation through card payment to license certificate generation. It also covers exclusive license preset management and safe producer finance references for approved integrations.

Base URL: https://open.beatpass.ca/api/v1

Authentication: All endpoints require a valid Bearer token unless noted otherwise.

---

Track Purchases

Calculate Price

Get pricing details for a track before initiating purchase.

POST /api/v1/tracks/{track}/purchase/calculate-price

track · integer · required

Track ID to get pricing for.

Response:

{
  "status": "success",
  "data": {
    "base_price": 29.99,
    "platform_fee": 4.50,
    "total_amount": 29.99,
    "currency": "USD",
    "is_exclusive": true
  }
}

---

Initiate Purchase

Start the purchase flow by creating a Stripe PaymentIntent.

POST /api/v1/tracks/{track}/purchase/initiate

track · integer · required

Track ID to purchase.

Response:

{
  "status": "success",
  "data": {
    "client_secret": "pi_xxx_secret_xxx",
    "purchase_id": 42,
    "pricing": {
      "base_price": 29.99,
      "platform_fee": 4.50,
      "total_amount": 29.99,
      "currency": "USD"
    }
  }
}

Use the client_secret with Stripe.js on the frontend to complete payment confirmation. Do not store or log client secrets.

Common Errors:

Error	Code	Cause
Track purchases not enabled	403	Feature disabled in config
Cannot purchase own track	422	Buyer is the track artist
Already purchased	422	User already owns license
Artist not set up for payments	422	Artist is not payout-ready

---

Check Purchase Status

Check whether the authenticated user has purchased a specific track.

GET /api/v1/tracks/{track}/purchase/status

Response:

{
  "status": "success",
  "data": {
    "has_purchased": true,
    "can_purchase": false,
    "reason": "already_purchased"
  }
}

---

User Purchases

Get the authenticated user’s purchase history.

GET /api/v1/purchases

per_page · integer

Results per page. Default: 15.

---

Artist Sales

Get sales data for the authenticated artist, including payout and balance summary fields when available.

GET /api/v1/artist/sales

Response:

{
  "status": "success",
  "data": {
    "earnings": {
      "total_sales": 12,
      "total_revenue": 245.50,
      "total_revenue_formatted": "\$245.50 USD",
      "pending_payout": 89.00,
      "paid_out": 156.50,
      "currency": "USD"
    },
    "recent_purchases": [
      {
        "id": 1,
        "track_id": 42,
        "track_name": "Summer Vibes",
        "artist_amount": 25.49,
        "total_amount": 29.99,
        "platform_fee": 4.50,
        "status": "succeeded",
        "purchased_at": "2025-01-15 14:30:00"
      }
    ]
  }
}

---

Purchase Flow

1. Calculate Price

   Call POST /tracks/{track}/purchase/calculate-price to get current pricing.

2. Initiate Purchase

   Call POST /tracks/{track}/purchase/initiate to create a Stripe PaymentIntent.

3. Confirm Payment

   Use the returned client_secret with Stripe.js confirmCardPayment() on the frontend.

4. Webhook Confirmation

   Stripe sends a payment_intent.succeeded webhook to BeatPass. The platform activates the license and generates a certificate.

5. Access License

   The buyer can download the track and retrieve their license certificate.

---

License Certificates

Generate License

Generate a license certificate for a purchased track.

POST /api/v1/tracks/{track}/generate-license

Check License

Check if a license exists for a track.

GET /api/v1/tracks/{track}/check-license

Batch Check Licenses

Check licenses for multiple tracks at once.

POST /api/v1/tracks/check-licenses-batch

View License Certificate

Retrieve the license certificate data for a purchased track.

GET /api/v1/tracks/{track}/license-certificate

track · integer · required

Track ID to retrieve the license certificate for.

Download License PDF

Download the license certificate as a PDF document.

GET /api/v1/tracks/{track}/download-license-pdf

Verify License (Public)

Verify a license certificate by its UUID. This endpoint does not require authentication.

GET /api/v1/verify-license/{uuid}

uuid · string · required

License certificate UUID.

Revoke License

Revoke a previously issued license.

POST /api/v1/licenses/{uuid}/revoke

User Licenses

Get all license certificates for the authenticated user.

GET /api/v1/user/licenses

---

Exclusive License Presets

Manage reusable pricing presets — exclusive license presets — for exclusive license sales.

List Presets

GET /api/v1/exclusive-license-presets

Get Default Config

Retrieve the default exclusive license configuration.

GET /api/v1/exclusive-license-presets/default-config

Get Preset

GET /api/v1/exclusive-license-presets/{preset}

Create Preset

POST /api/v1/exclusive-license-presets

Update Preset

PUT /api/v1/exclusive-license-presets/{preset}

Delete Preset

DELETE /api/v1/exclusive-license-presets/{preset}

Set Default Preset

POST /api/v1/exclusive-license-presets/{preset}/set-default

---

Artist Exclusive License Default

Manage the artist’s default exclusive license configuration, auto-applied to new tracks.

Get Default

GET /api/v1/artist/exclusive-license-default

Set Default

POST /api/v1/artist/exclusive-license-default

---

Coupon Validation

Validate a discount code during checkout. This is the only user-facing coupon endpoint — coupon creation and management require administrative access.

Validate Coupon Code

Check if a coupon code is valid and calculate the discount amount.

POST /api/v1/coupons/validate

code · string · required

Coupon code to validate.

product_id · integer

Product/plan ID the coupon will be applied to.

price_id · integer

Price ID the coupon will be applied to.

amount · number

Original amount (before discount) for calculating savings.

Success Response:

{
  "status": "success",
  "coupon": {
    "id": 1,
    "code": "SAVE20",
    "type": "percentage",
    "amount": 20
  },
  "discount_amount": 5.99,
  "final_amount": 23.99,
  "savings": 5.99,
  "valid": true
}

Error Responses:

Error	Code	Cause
Invalid or expired coupon code	422	Code not found or expired
You cannot use this coupon	422	User-specific restriction
Cannot be applied to selected plan	422	Coupon not valid for this product

---

Producer Payout Setup

BEATPAY bank payout setup is an in-product Producer Finances workflow, not a public developer integration surface. Do not build integrations against undocumented payout setup routes.

Stripe Connect Status

Check whether the authenticated artist has completed Stripe Connect onboarding when Stripe is the payout setup shown to that artist.

GET /api/v1/artist/stripe-connect/status

Stripe Connect Onboarding Link

Generate a Stripe Connect onboarding link for the authenticated artist when Stripe Connect onboarding is available.

POST /api/v1/artist/stripe-connect/onboard

View Legacy Stripe Finances

Get the artist’s legacy Stripe Connect financial overview where available.

GET /api/v1/artist/stripe-connect/finances

---

Related Resources

Webhooks

Payment event processing overview for purchase confirmation.

Error Catalog

Purchase and licensing error codes.