Skip to main content

​
Overview

The Commerce & Licensing API handles the complete purchase lifecycle — from pricing calculation through Stripe payment to license certificate generation. It also covers exclusive license preset management and Stripe Connect onboarding for producers.
Base URL: https://open.beatpass.ca/api/v1Authentication: 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 . 
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:
ErrorCodeCause
Track purchases not enabled403Feature disabled in config
Cannot purchase own track422Buyer is the track artist
Already purchased422User already owns license
Artist not set up for payments422Artist lacks active Stripe Connect

​
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 Stripe Connect balance. 
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 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 — — 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:
ErrorCodeCause
Invalid or expired coupon code422Code not found or expired
You cannot use this coupon422User-specific restriction
Cannot be applied to selected plan422Coupon not valid for this product

​
Stripe Connect

​
Check Onboarding Status

Check whether the authenticated artist has completed Stripe Connect onboarding. 
GET /api/v1/artist/stripe-connect/status
Generate a Stripe Connect onboarding link for the authenticated artist. 
POST /api/v1/artist/stripe-connect/onboard

​
View Finances

Get the artist’s Stripe Connect financial overview. 
GET /api/v1/artist/stripe-connect/finances

Webhooks

Stripe webhook events for purchase confirmation.

Error Catalog

Purchase and licensing error codes.
Last modified on February 10, 2026