Create Subscription

Create subscription

Create a new subscription for a customer. A subscription ties a customer to a product and defines a billing interval and payment method. The subscription starts in pending_payment status until the first payment is received.

POST /api/v1/subscriptions/

Authentication

x-api-key: your_api_key
x-api-secret: your_api_secret

Request body

customerId

string

required

UUID of the customer to subscribe. The customer must already exist in your account.

productId

string

required

UUID of the product the subscription is for. The product’s price becomes the recurring billing amount.

interval

string

required

Billing frequency. One of: daily, every_3_days, weekly, biweekly, monthly, quarterly, biannual, yearly.

paymentMethod

string

required

How the subscription will be collected. One of:

card — charge the customer’s card on each billing cycle.
manual — you manually mark each cycle as paid.
va — generate a fresh virtual account for each billing cycle.

graceDays

integer

Number of days after a missed payment before the subscription is automatically canceled. Defaults to 3 if not provided.

metadata

object

Arbitrary key-value pairs for your own reference.

checkoutCallbackUrl

string

An HTTPS URL Hyparrow will POST to when a checkout-link payment for this subscription changes status (completed, pending, or failed).

Example request

curl --request POST \
  --url https://api.hyparrow.com/api/v1/subscriptions/ \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: your_api_key' \
  --header 'x-api-secret: your_api_secret' \
  --data '{
    "customerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "productId": "p1q2r3s4-t5u6-7890-vwxy-z12345678901",
    "interval": "monthly",
    "paymentMethod": "va",
    "graceDays": 5,
    "metadata": {
      "plan": "starter"
    }
  }'

Example response

201 Created

{
  "success": true,
  "message": "Subscription created",
  "data": {
    "id": "sub-uuid-abcd1234",
    "customerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "productId": "p1q2r3s4-t5u6-7890-vwxy-z12345678901",
    "interval": "monthly",
    "amount": 10000,
    "currency": "NGN",
    "paymentMethod": "va",
    "status": "pending_payment",
    "graceDays": 5,
    "source": "api",
    "metadata": {
      "plan": "starter"
    },
    "createdAt": "2024-04-01T08:00:00Z",
    "updatedAt": "2024-04-01T08:00:00Z"
  }
}

Response fields

data.id

string

Unique subscription UUID.

data.interval

string

The billing interval as provided.

data.amount

number

Recurring billing amount pulled from the product’s price.

data.currency

string

3-letter currency code inherited from the product.

data.status

string

Subscription status. Starts as pending_payment. Transitions to active once the first payment is received. Other values: canceled, expired.

data.nextBillingAt

string

ISO 8601 timestamp of the next scheduled billing date. Populated after first payment.

data.graceDays

integer

Days of grace after a missed payment before auto-cancellation.

List subscriptions

Returns a paginated list of all subscriptions for your account.

GET /api/v1/subscriptions/

Query parameters

page

integer

Page number. Defaults to 1.

limit

integer

Results per page. Defaults to 20.

status

string

Filter by status. One of: active, pending_payment, canceled, expired.

Example request

cURL

curl --request GET \
  --url 'https://api.hyparrow.com/api/v1/subscriptions/?page=1&limit=20&status=active' \
  --header 'x-api-key: your_api_key' \
  --header 'x-api-secret: your_api_secret'

Example response

200 OK

{
  "success": true,
  "data": [
    {
      "id": "sub-uuid-abcd1234",
      "customerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "productId": "p1q2r3s4-t5u6-7890-vwxy-z12345678901",
      "interval": "monthly",
      "amount": 10000,
      "currency": "NGN",
      "paymentMethod": "va",
      "status": "active",
      "nextBillingAt": "2024-05-01T00:00:00Z",
      "createdAt": "2024-04-01T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

Get subscription

Retrieve a single subscription by its ID.

GET /api/v1/subscriptions/:subscriptionId

Path parameters

subscriptionId

string

required

UUID of the subscription to retrieve.

Example request

cURL

curl --request GET \
  --url https://api.hyparrow.com/api/v1/subscriptions/sub-uuid-abcd1234 \
  --header 'x-api-key: your_api_key' \
  --header 'x-api-secret: your_api_secret'

Example response

200 OK

{
  "success": true,
  "data": {
    "id": "sub-uuid-abcd1234",
    "customerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "productId": "p1q2r3s4-t5u6-7890-vwxy-z12345678901",
    "interval": "monthly",
    "amount": 10000,
    "currency": "NGN",
    "paymentMethod": "va",
    "status": "active",
    "startedAt": "2024-04-01T09:00:00Z",
    "currentPeriodStart": "2024-04-01T09:00:00Z",
    "currentPeriodEnd": "2024-04-30T23:59:59Z",
    "nextBillingAt": "2024-05-01T00:00:00Z",
    "graceDays": 5,
    "createdAt": "2024-04-01T08:00:00Z",
    "updatedAt": "2024-04-02T10:00:00Z"
  }
}