Subscriptions

Manage customer subscriptions.

Create Subscription

Initiates a new subscription in PAUSED state and returns a checkout URL for the customer to complete the first payment.

Endpoint: POST /subscription/create

Request Body

Field	Type	Description	Required
planId	string	ID of the subscription plan (UUID)	Yes
customerEmail	string	Email address of the customer	Yes
customerName	string	Name of the customer	No
metadata	object	Additional metadata for the subscription	No

Example Request

{
  "planId": "550e8400-e29b-41d4-a716-446655440000",
  "customerEmail": "john@example.com",
  "customerName": "John Doe"
}

Success Response

{
  "success": true,
  "data": {
    "subscriptionId": "uuid-v4-subscription-id",
    "checkoutUrl": "https://paysgator.com/checkout/sub_...",
    "status": "PAUSED"
  }
}

Get Subscription

Retrieve details of a specific subscription.

Endpoint: GET /subscription/{id}

Parameters

Parameter	Type	Description	Required
id	string	The UUID of the subscription	Yes

Success Response

{
  "success": true,
  "data": {
    "id": "uuid-v4-subscription-id",
    "planId": "uuid-v4-plan-id",
    "customerEmail": "john@example.com",
    "status": "ACTIVE",
    "currentPeriodStart": "2023-10-27T10:00:00Z",
    "currentPeriodEnd": "2023-11-27T10:00:00Z",
    "createdAt": "2023-10-27T10:00:00Z"
  }
}

List Subscriptions

List all subscriptions for your company. You can filter by customer email, status, or plan ID.

Endpoint: GET /subscriptions

Query Parameters

Parameter	Type	Description	Required
customerEmail	string	Filter by customer email	No
status	string	Filter by status (ACTIVE, CANCELED, PAST_DUE, PAUSED)	No
planId	string	Filter by plan ID (UUID)	No

Success Response

{
  "success": true,
  "data": [
    {
      "id": "uuid-v4-subscription-id",
      "planId": "uuid-v4-plan-id",
      "customerEmail": "john@example.com",
      "status": "ACTIVE",
      "currentPeriodStart": "2023-10-27T10:00:00Z",
      "currentPeriodEnd": "2023-11-27T10:00:00Z",
      "createdAt": "2023-10-27T10:00:00Z"
    }
  ]
}

Update Subscription

Update the status of an existing subscription. Use this endpoint to cancel, pause, or resume a subscription.

Endpoint: PATCH /subscriptions/{id}

Parameters

Parameter	Type	Description	Required
id	string	The UUID of the subscription	Yes

Request Body

Field	Type	Description	Required
action	string	Action to perform: cancel, pause, or resume	Yes

Example Request

{
  "action": "cancel"
}

Success Response

{
  "id": "uuid-v4-subscription-id",
  "status": "CANCELED",
  "customerEmail": "customer@example.com",
  "currentPeriodEnd": "2023-11-27T10:00:00Z"
}