Subscriptions API

The Subscriptions API allows you to create and manage recurring billing for your customers.

The Subscription Object

{
  "id": "sub_abc123def456",
  "object": "subscription",
  "status": "active",
  "customer": "cus_xyz789",
  "plan": {
    "id": "plan_abc123",
    "name": "Pro Monthly",
    "amount": 5000,
    "currency": "GHS",
    "interval": "month"
  },
  "current_period_start": "2024-01-15T00:00:00Z",
  "current_period_end": "2024-02-15T00:00:00Z",
  "trial_start": "2024-01-01T00:00:00Z",
  "trial_end": "2024-01-15T00:00:00Z",
  "cancel_at_period_end": false,
  "canceled_at": null,
  "ended_at": null,
  "metadata": {},
  "created_at": "2024-01-01T10:00:00Z"
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier
`object`	string	Always `"subscription"`
`status`	string	`active`, `incomplete`, `paused`, `canceled`
`customer`	string	Customer ID
`plan`	object	The subscription plan
`current_period_start`	string	Start of current billing period
`current_period_end`	string	End of current billing period
`trial_start`	string	Trial start timestamp
`trial_end`	string	Trial end timestamp
`cancel_at_period_end`	boolean	Cancel at end of period
`canceled_at`	string	When subscription was canceled
`ended_at`	string	When subscription ended
`metadata`	object	Custom metadata
`created_at`	string	Creation timestamp

Create a Subscription

Creates a new subscription for a customer.

POST /v1/subscriptions

Request Body

Parameter	Type	Required	Description
`customer`	string	Yes	Customer ID
`plan`	string	Yes	Plan ID
`default_payment_method`	string	No	Payment method ID
`trial_end`	string	No	ISO 8601 timestamp for trial end (overrides plan trial)
`metadata`	object	No	Custom metadata

curl -X POST https://api.shikacreators.com/v1/subscriptions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_xyz789",
    "plan": "plan_abc123"
  }'

const subscription = await shikacreators.subscriptions.create({
  customer: 'cus_xyz789',
  plan: 'plan_abc123'
})

subscription = client.subscriptions.create(
    customer='cus_xyz789',
    plan='plan_abc123'
)

$subscription = $shikacreators->subscriptions->create([
    'customer' => 'cus_xyz789',
    'plan' => 'plan_abc123'
]);

Retrieve a Subscription

Retrieves a subscription by ID.

GET /v1/subscriptions/:id

curl https://api.shikacreators.com/v1/subscriptions/sub_abc123def456 \
  -H "Authorization: Bearer sk_test_..."

const subscription = await shikacreators.subscriptions.retrieve('sub_abc123def456')

subscription = client.subscriptions.retrieve('sub_abc123def456')

Update a Subscription

Updates a subscription.

PATCH /v1/subscriptions/:id

Request Body

Parameter	Type	Description
`cancel_at_period_end`	boolean	Cancel at end of current period
`default_payment_method`	string	Payment method ID
`metadata`	object	Custom metadata
`pause_collection`	object	Pause billing (e.g., `{ "behavior": "void", "resumes_at": "2024-03-01T00:00:00Z" }`)

curl -X PATCH https://api.shikacreators.com/v1/subscriptions/sub_abc123def456 \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "cancel_at_period_end": true
  }'

const subscription = await shikacreators.subscriptions.update('sub_abc123def456', {
  cancel_at_period_end: true
})

subscription = client.subscriptions.update('sub_abc123def456',
    cancel_at_period_end=True
)

Cancel a Subscription

Cancels a subscription immediately.

DELETE /v1/subscriptions/:id

Request Body

Parameter	Type	Description
`cancellation_reason`	string	Optional reason for cancellation

To cancel at the end of the current billing period instead of immediately, use the update endpoint with cancel_at_period_end: true.

# Cancel at period end (via update)
curl -X PATCH https://api.shikacreators.com/v1/subscriptions/sub_abc123def456 \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"cancel_at_period_end": true}'

# Cancel immediately
curl -X DELETE https://api.shikacreators.com/v1/subscriptions/sub_abc123def456 \
  -H "Authorization: Bearer sk_test_..."

// Cancel at period end (via update)
await shikacreators.subscriptions.update('sub_abc123def456', {
  cancel_at_period_end: true
})

// Cancel immediately
await shikacreators.subscriptions.cancel('sub_abc123def456')

# Cancel at period end (via update)
client.subscriptions.update('sub_abc123def456',
    cancel_at_period_end=True
)

# Cancel immediately
client.subscriptions.cancel('sub_abc123def456')

Pause a Subscription

Pauses a subscription by updating it with pause_collection.

PATCH /v1/subscriptions/:id

curl -X PATCH https://api.shikacreators.com/v1/subscriptions/sub_abc123def456 \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "pause_collection": {
      "behavior": "void",
      "resumes_at": "2024-03-01T00:00:00Z"
    }
  }'

const subscription = await shikacreators.subscriptions.update('sub_abc123def456', {
  pause_collection: {
    behavior: 'void',
    resumes_at: '2024-03-01T00:00:00Z'
  }
})

subscription = client.subscriptions.update('sub_abc123def456',
    pause_collection={
        'behavior': 'void',
        'resumes_at': '2024-03-01T00:00:00Z'
    }
)

Resume a Subscription

Resumes a paused subscription.

POST /v1/subscriptions/:id/resume

curl -X POST https://api.shikacreators.com/v1/subscriptions/sub_abc123def456/resume \
  -H "Authorization: Bearer sk_test_..."

const subscription = await shikacreators.subscriptions.resume('sub_abc123def456')

subscription = client.subscriptions.resume('sub_abc123def456')

List Subscriptions

Returns a list of subscriptions.

GET /v1/subscriptions

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (1-100)
`starting_after`	string	Cursor for pagination
`customer`	string	Filter by customer ID
`status`	string	Filter by status
`plan`	string	Filter by plan ID

curl "https://api.shikacreators.com/v1/subscriptions?status=active&limit=10" \
  -H "Authorization: Bearer sk_test_..."

const subscriptions = await shikacreators.subscriptions.list({
  status: 'active',
  limit: 10
})

subscriptions = client.subscriptions.list(status='active', limit=10)

Response

{
  "object": "list",
  "data": [
    {
      "id": "sub_abc123def456",
      "object": "subscription",
      "status": "active",
      ...
    }
  ],
  "has_more": false,
  "url": "/v1/subscriptions"
}

Subscriptions

On this page