Subscriptions API

Manage recurring subscriptions in your store.

List Subscriptions

GET /api/external/v1/subscriptions

Query Parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
per_page	integer	Items per page (default: 15, max: 100)
status	string	Filter: active, trialing, past_due, canceled, incomplete
customer_id	integer	Filter by customer ID
product_id	integer	Filter by product ID
sort	string	Sort field: created_at, current_period_end
order	string	Sort order: asc, desc

Example Request

curl -X GET "https://yourstore.pixlpay.net/api/external/v1/subscriptions?status=active" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "customer_id": 42,
      "product_id": 5,
      "status": "active",
      "payment_gateway": "stripe",
      "gateway_subscription_id": "sub_1234567890",
      "product": {
        "id": 5,
        "name": "VIP Monthly",
        "price": "9.99",
        "currency": "usd"
      },
      "customer": {
        "id": 42,
        "email": "player@example.com",
        "username": "Player123"
      },
      "current_period_start": "2025-01-01T00:00:00Z",
      "current_period_end": "2025-02-01T00:00:00Z",
      "trial_ends_at": null,
      "cancel_at_period_end": false,
      "canceled_at": null,
      "created_at": "2025-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 15,
    "total": 42
  }
}

Get Single Subscription

GET /api/external/v1/subscriptions/{id}

Example Request

curl -X GET "https://yourstore.pixlpay.net/api/external/v1/subscriptions/1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

{
  "success": true,
  "data": {
    "id": 1,
    "customer_id": 42,
    "product_id": 5,
    "status": "active",
    "payment_gateway": "stripe",
    "gateway_subscription_id": "sub_1234567890",
    "gateway_customer_id": "cus_1234567890",
    "product": {
      "id": 5,
      "name": "VIP Monthly",
      "description": "Monthly VIP membership with exclusive perks",
      "price": "9.99",
      "currency": "usd",
      "formatted_price": "$9.99"
    },
    "customer": {
      "id": 42,
      "email": "player@example.com",
      "username": "Player123",
      "discord_id": "123456789"
    },
    "quantity": 1,
    "trial_ends_at": null,
    "current_period_start": "2025-01-01T00:00:00Z",
    "current_period_end": "2025-02-01T00:00:00Z",
    "cancel_at_period_end": false,
    "canceled_at": null,
    "ended_at": null,
    "is_active": true,
    "is_on_trial": false,
    "is_past_due": false,
    "is_canceled": false,
    "days_until_renewal": 12,
    "renewal_date": "February 1, 2025",
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-01T00:00:00Z"
  }
}

Cancel Subscription

Cancel a subscription immediately or at the end of the billing period.

POST /api/external/v1/subscriptions/{id}/cancel

Request Body

Parameter	Type	Required	Description
immediately	boolean	No	If true, cancel immediately. If false (default), cancel at period end.

Example Request (Cancel at Period End)

curl -X POST "https://yourstore.pixlpay.net/api/external/v1/subscriptions/1/cancel" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"immediately": false}'

Response

{
  "success": true,
  "data": {
    "id": 1,
    "status": "active",
    "cancel_at_period_end": true,
    "canceled_at": "2025-01-20T14:30:00Z",
    "current_period_end": "2025-02-01T00:00:00Z"
  },
  "message": "Subscription will be canceled at the end of the billing period"
}

Example Request (Cancel Immediately)

curl -X POST "https://yourstore.pixlpay.net/api/external/v1/subscriptions/1/cancel" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"immediately": true}'

Response

{
  "success": true,
  "data": {
    "id": 1,
    "status": "canceled",
    "cancel_at_period_end": false,
    "canceled_at": "2025-01-20T14:30:00Z",
    "ended_at": "2025-01-20T14:30:00Z"
  },
  "message": "Subscription canceled successfully"
}

Resume Subscription

Resume a subscription that was scheduled for cancellation (before it actually ends).

POST /api/external/v1/subscriptions/{id}/resume

TIP

This only works for subscriptions with cancel_at_period_end: true that haven't reached their cancellation date yet. Already-canceled subscriptions cannot be resumed.

Example Request

curl -X POST "https://yourstore.pixlpay.net/api/external/v1/subscriptions/1/resume" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

{
  "success": true,
  "data": {
    "id": 1,
    "status": "active",
    "cancel_at_period_end": false,
    "canceled_at": null,
    "current_period_end": "2025-02-01T00:00:00Z"
  },
  "message": "Subscription resumed successfully"
}

Subscription Object

Field	Type	Description
id	integer	Unique identifier
customer_id	integer	ID of the customer
product_id	integer	ID of the subscription product
status	string	Current status (see below)
payment_gateway	string	Payment gateway: stripe, paypal, mollie, etc.
gateway_subscription_id	string	Payment gateway's subscription ID
gateway_customer_id	string	Payment gateway's customer ID
product	object	Product details
customer	object	Customer details
quantity	integer	Subscription quantity (usually 1)
trial_ends_at	string	Trial end timestamp (null if no trial)
current_period_start	string	Current billing period start
current_period_end	string	Current billing period end
cancel_at_period_end	boolean	Whether scheduled to cancel at period end
canceled_at	string	When cancellation was requested
ended_at	string	When subscription actually ended
is_active	boolean	Whether subscription is currently active
is_on_trial	boolean	Whether subscription is in trial period
is_past_due	boolean	Whether payment is past due
is_canceled	boolean	Whether subscription is canceled
days_until_renewal	integer	Days until next billing
renewal_date	string	Human-readable renewal date
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp

Subscription Statuses

Status	Description
active	Subscription is active and payments are current
trialing	Subscription is in trial period
past_due	Payment failed, subscription still active pending retry
canceled	Subscription has been canceled and ended
incomplete	Initial payment failed, awaiting action
incomplete_expired	Incomplete subscription expired
unpaid	Payment failures exhausted, subscription paused

Product Object (Nested)

Field	Type	Description
id	integer	Product ID
name	string	Product name
description	string	Product description
price	string	Subscription price per period
currency	string	Currency code (e.g., usd, eur)
formatted_price	string	Human-readable price (e.g., $9.99)

Customer Object (Nested)

Field	Type	Description
id	integer	Customer ID
email	string	Customer email
username	string	Display username
discord_id	string	Discord user ID (if connected)

Errors

Status	Error	Description
400	Bad Request	Cannot cancel already-canceled subscription
400	Bad Request	Cannot resume non-canceled subscription
401	Unauthorized	Invalid or missing token
403	Forbidden	Token lacks required scope
404	Not Found	Subscription doesn't exist
422	Unprocessable	Invalid request parameters

Required Scopes

Endpoint	Required Scope
GET /subscriptions	subscriptions:read
GET /subscriptions/{id}	subscriptions:read
POST /subscriptions/{id}/cancel	subscriptions:write
POST /subscriptions/{id}/resume	subscriptions:write

Webhook Events

Subscribe to these events to stay updated on subscription changes:

Event	Description
subscription.created	New subscription created
subscription.updated	Subscription status or details changed
subscription.canceled	Subscription was canceled
subscription.renewed	Subscription successfully renewed
subscription.payment_failed	Renewal payment failed

See Webhook Events for payload details.